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Document Structure 


This manual describes the VAX DOCUMENT generic markup system and the 
tags used to create all VAX DOCUMENT types of documentation. 


e Chapter 1 provides an introduction of the VAX DOCUMENT system. 


¢ Chapters 2 and 3 describe how to create input files and use basic text 
elements within those input files. 


¢ Chapter 4 discusses processing of input files, including how to build a 
book. 


¢ Chapter 5 describes some methods to troubleshoot input files. 


e Chapter 6 explains how a user can cross-reference symbol-names 
throughout files and books. 


e Chapter 7 describes how to create a table of contents, an index, or a 
master index. 


¢ Chapter 8 explains the coding of some special VAX DOCUMENT features. 


¢ Chapter 9 is the reference section of the book, containing an alphabetic 
listing of all the SDML tags that are used in any doctype. Each tag is 
explained in full, with examples to illustrate the correct coding. 


e Appendix A explains the DOCUMENT command and the command’s 
parameters and qualifiers. 


e Appendix B is an overview of the Language-Sensitive Editor that can be 
used with VAX DOCUMENT. 


° Appendix C lists and explains the error messages users could see when 
processing source files. 


e Appendix D is a table of all SDML tags (both global and doctype-specific). 
It also indicates in which doctype the tag is valid and summarizes the 
tag’s use. 


The VAX DOCUMENT User Manual, Volume 2 provides a description of the 
tags used in specific doctypes. 


The VAX DOCUMENT Design Samples manual provides information on each 
of the doctyp2 designs available in VAX DOCUMENT and provides samples 
of each design. 





Intended Audience 


This book is intended for writers, editors, and general users who wish to 
produce technical manuals, brochures, or even business letters or overhead 
slides using VAX DOCUMENT. Familiarity with a text editor is presumed, as 
is a basic knowledge of the VMS operating system. 
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Associated Documents 


The reader of this manual should be familiar with: 


e Step-by-Step: Writing with VAX DOCUMENT 


Other books in the documentation set for VAX DOCUMENT Version 1.1 
which describe the more technical aspects of the product are: 


e VAX DOCUMENT User Manual, Volume 2 

e VAX DOCUMENT Doctype Designer’s Guide 
e VAX DOCUMENT Installation Guide 

e VAX DOCUMENT Design Samples 





Conventions 


xvi 


Within both the VAX DOCUMENT User Manuals, Volumes 1 and 2, capitalized 
words within syntax statements indicate specific commands or keywords to be 
entered. Lowercase words indicate user-specified parameters or arguments. 
Optional items within syntax statements are enclosed in brackets. 


Within the reference chapters in the VAX DOCUMENT User Manuals, Volumes 
1 and 2, the discussion of each tag follows a fixed order. First, the name of 
the tag is followed by a brief overview that describes the purpose of the tag. 
Following the overview is a format section that displays the syntax of the tag: 
any optional or required arguments and the information required, any related 
tags, any restrictions on the use of the tag, and any required terminators, if 
needed. 


The category of “related tag” has been defined broadly. A tag is related to the 
tag under discussion if one of the following criteria is met: 


¢ It is required for use of the tag under discussion. 
e It marks a text element of the same kind as the tag under discussion. 


e It is commonly used with the tag under discussion. 


Following the format section is an optional description section. The 
description expands the overview and presents more detailed information 
on the use of the tag. Not every tag requires a description section. 


The discussion of a tag concludes with at least one example, or a reference 
to an example. The example shows how the tag is used in an SDML file and 
what the formatted result is when the file is processed for printing. 


Output examples may vary depending on the doctype you processed the 
example under or on whether any doctype modifications have been made 
to your local installation of VAX DOCUMENT. Each output example is 
introduced by a form of the sentence “This example may produce the 
following output” to remind you that the output examples may vary. 


Preface 


The following table lists some of the typographical conventions used in 


this manual. 





Convention 


Meaning 





RET 


$ TYPE MYFILE.DAT 


input-file, ... 


[logical-name] 


quotation marks 
apostrophes 


In examples, a key name (usually abbreviated) shown 
within a box indicates that you press a key on the 
keyboard; in text, a key name is not enclosed in a 
box. In this example, the key is the RETURN key. 
(Note that the RETURN key is not usually shown 

in syntax statements or in all examples; however, 
you must press the RETURN key after entering a 
command or responding to a prompt.) 


In examples, a vertical ellipsis represents the omission 
of data that the system would display in response to 
a command or of data a user would enter. 


In examples, a horizontal ellipsis indicates that 
additional parameters, values, or other information 
can be entered, that preceding items can be repeated 
one or more times, or that optional arguments in a 
statement have been omitted. 


Brackets indicate that the enclosed item is optional. 
(Brackets are not, however, optional in the syntax of 
a directory name in a file specification.) 


The term quotation marks is used to refer to double 
quotation marks ("). The term apostrophe (’) is used 
to refer to a single quotation mark. 


New and Changed Features 


The following table lists the new and changed SDML tags for VAX 
DOCUMENT Version 1.1 (see Chapter 9 for a complete description of any of 
these tags): 


Type 
New 


Changed 


New 


Changed 


New 


New 


Changed 


SDML Tag 
<DELAYED> 


<FIGURE _FILE> 


<FILE_SPEC> 


<ICON_FILE> 


<SET_FIGURE_FILE_ 
SPACING_DEFAULT > 


<SET_TABLE_ROW_ 
BREAK_DEFAULT > 


<TABLE_ATTRIBUTES> 


Description 


A doctype-independent tag that allows 
you to specify text that contains SDML 
tags in an argument to another tag. 


This tag now accepts a keyword 
argument of PS rather than POST to 
specify a POSTSCRIPT~ device, and a 
keyword argument of LINE rather than 
LINE_PRINTER to specify a monospaced 
line printer. 


A doctype-independent tag that allows 
you to specify a file specification 
containing angle brackets as an 
argument to an SDML tag without 
VAX DOCUMENT interpreting that file 
specification as an SDML tag. 


This tag now accepts a keyword 
argument of PS rather than POST to 
specify a POSTSCRIPT device, and a 
keyword argument of LINE rather than 
LINE_PRINTER to specify a monospaced 
line printer. 


A doctype-independent tag that allows 
you to override the default amount of 
blank space that appears before and 
after an included graphics file. 


A doctype-independent tag that allows 
you to override the default value for a 
multipage table's first valid break. 


This tag now accepts two new keyword 
arguments. The CONTROLLED keyword 
specifies that the breaking of a table will 
be under explicit control of the <TABLE_ 
ROW_BREAK> tags only. The SINGLE_ 
SPACED keyword specifies that the rows 
in a table are to be single-spaced. 


®PostScript is a registered trademark of Adobe Systems, Inc. 
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New and Changed Features 


The following table lists the new and changed qualifiers and parameters for 
VAX DOCUMENT Version 1.1 (see Appendix A for a complete description of 
any of these parameters or qualifiers): 


Qualifier 
Type or Parameter Description 
New /OUTPUT Allows the user to redirect the VAX 


DOCUMENT output file to a file other 
than the default. 


Changed /DEVICE_CONVERTER The MULTINATIONAL_CHARACTER_ 
SET keyword is no longer valid; by 
default the DEC multinational character 
set is used for line printer type devices. 


The new FALLBACK keyword allows 
users to disable the DEC multinational 
character set for a seven-bit monospaced 
device. 


Changed LINE_PRINTER LINE_PRINTER is no longer a default 
destination keyword for VAX 
DOCUMENT Version 1.1; the new default 
keyword for that type of destination is 
LINE. 


Changed LNO3_LASER_PRINTER LNO3_LASER_PRINTER is no longer a 
default destination keyword for VAX 
DOCUMENT Version 1.1; the new default 
keyword for that type of destination is 
LNO3. 


Changed /MASTER_INDEX Master index processing no longer 
terminates at the text processing stage; 
it now runs to completion and generates 
a printable file. Also all the keywords 
accepted by the /INDEX qualifier are 
now accepted by the /MASTER_INDEX 
qualifier. 


Changed POSTSCRIPT POSTSCRIPT is no longer a default 
destination keyword for VAX 
DOCUMENT Version 1.1; the new default 
keyword for that type of destination is 
PS. In addition the default file types 
associated with the POSTSCRIPT. 
keyword have been changed from 
DVI_POST to DVI_PS, and POST to PS. 


1 _ Introduction to VAX DOCUMENT 


The VAX DOCUMENT system for producing technical documentation is 
designed to fully automate the creation of documentation from generically 
coded input files. VAX DOCUMENT supports the creation of technical 
documentation from the earliest stages of a document’s planning to the final 
copy that emerges ready for production. 


The basis of the VAX DOCUMENT system is an integrated series of software 
processors that convert generically coded source files into formatted final 
output. This integrated system allows users to perform the following 
functions: 


e Write and maintain files for a document 
e¢ Produce output for a wide range of devices 


e¢ Correct errors and incorporate changes into files with a text editor 


Although it uses a powerful, high-level language for text processing, VAX 
DOCUMENT is not difficult to learn. One or two trial runs of an input file 
through the processors is all you need do to get a good grasp of the system. It 
is recommended that you work through the exercises in Step-by-Step: Writing 
with VAX DOCUMENT before you begin more complex production tasks. 


This chapter gives a brief overview of the VAX DOCUMENT system and 
introduces concepts you need to understand and use the system. 


1.1 The VAX DOCUMENT Documentation Set 


The books in the VAX DOCUMENT documentation set are written for three 
audiences: a writer or editor who will use VAX DOCUMENT to create 
documentation, a system manager who will install and maintain the system, 
and a doctype designer who will create new doctypes for local use. The 
documentation set includes the following books: 


e Step-by-Step: Writing with VAX DOCUMENT 
e VAX DOCUMENT User Manual, Volume 1 

e VAX DOCUMENT User Manual, Volume 2 

e VAX DOCUMENT Design Samples 

e VAX DOCUMENT Doctype Designer’s Guide 


New users of VAX DOCUMENT might want to start with Step-by-Step: 
Writing with VAX DOCUMENT for a beginning tutorial of how to use the 
system. The VAX DOCUMENT User Manual, Volume 1 contains more detailed 
information, including a reference chapter of the global tags (tags available 
in all the doctypes). The VAX DOCUMENT User Manual, Volume 2 contains 
detailed information on the doctype-specific tags. 
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Doctype designers might want to start with Step-by-Step: Writing with VAX 
DOCUMENT and then progress to the VAX DOCUMENT Doctype Designer's 
Guide. The VAX DOCUMENT Design Samples shows the various doctype 
designs available in each of the VAX DOCUMENT doctypes. 


1.2 Features of VAX DOCUMENT 


The following are some of the most important features of VAX DOCUMENT. 


Text Formatting 


e Adjustable text alignment 


e All PostScripT® and LNO3 fonts support the full DIGITAL Multinational 
Character Set 


¢ Automatic page numbering 


e Automatic headers/footers 


e Controllable hyphenation 


¢ Multicolumn output 


Publishing 


e A sophisticated table utility for creating tables in multicolumn formats 
e Automated cross-referencing 

e Automated collation of table of contents, chapters, and headings 

e Automated generation of indexes and master indexes 

e Automated generation of table of contents 

e Availability of 15 basic document designs 

e Batch or interactive processing support 


e Generation of footnotes in several formats 


Supported Output Devices 


e DIGITAL’s POSTSCRIPT devices, such as the PRINTSERVER 40 and the 


LNO3R SCRIPTPRINTER 


e Line printers 
¢ LNO3 and LNO3 PLUS laser printers 
e¢ Terminal display, to read output on a terminal screen 


e VMS Mail format, to read from within the VMS Mail Utility 


® PostScript is a registered trademark of Adobe Systems, Inc. 
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1.3 Using a Generic Markup Language 


The language that is used to mark up a file for processing through VAX 
DOCUMENT is referred to as generic because it is used, unchanged, to 
produce any type of document. Using a generic markup system requires a 
different perspective on writing than is needed when you use a formatting 
language (such as DIGITAL Standard Runoff). It takes time to become 
accustomed to thinking solely in terms of content rather than format. 

You need not think in terms of margins, spacing, and other formatting 
characteristics. Instead, when using a markup system like VAX DOCUMENT, 
you must think in terms of text elements. This means that for each individual 
element of text, such as the start of a paragraph, an emphasized word, a 
heading, and so on, you identify that text element for the processor by tagging 
it. 

For example, compare a sample of DIGITAL Standard Runoff (DSR) code to 
the code of VAX DOCUMENT. DSR is coded as follows: 


.b.1m5.nf.nj 

Here is a sample of text that could be 
processed by a text processor. 
.1m0.f.j. 


This method requires users to remember the current margins, the amount to 
indent the text, and so on, each time they type an example. Using SDML, 
the underlying format is controlled for consistency by the document type 
(doctype). The example is coded with tags that generically label the kind of 
text they are formatting: 


<CODE_EXAMPLE> 

Here is a sample of text that could be 
processed by a text processor. 
<ENDCODE_EXAMPLE> 


VAX DOCUMENT automatically specifies the correct formatting instructions 
for a chosen doctype, freeing the writer from the task of formatting text and 
allowing the writer to concentrate on the task of writing. 


The language that you use to tag.a file, the Standard DIGITAL Markup 
Language (SDML), contains a full set of tags for naming all the text elements 
commonly found in technical documentation. Tagging text elements is 
discussed in detail in Chapters 2 and 4. For now, just realize that you do 
not need to control the format as you write. The formatting is taken care of 
automatically during processing. 


eventually be processed through VAX DOCUMENT, always give the file an 
.SDML extension. 
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1.4 Introduction to the DOCUMENT Command Line 


One command, typed at the DCL prompt, is used to process any type of VAX 
DOCUMENT file: 


$ DOCUMENT input-file-spec doctype.design destination 
The DOCUMENT command requires three parameters: 
¢ Input-file-spec 


Specifies the input file for VAX DOCUMENT. This file is by default an 
SDML file containing SDML tags. However, it may also be one of the 
intermediate files generated by VAX DOCUMENT. 


¢ Doctype 


Specifies the document type keyword for which the input file should be 
processed. This keyword specifies the kind of document to be created 
(a letter, a software manual, a journal article, and so on). A doctype can 
comprise several different designs; in that case, the design keyword is 
specified after the doctype keyword, separated from it by a period. . 


e Destination 


Specifies the final processing destination for the input file. This keyword 
typically specifies a format used by a printer, but may specify formats for 
terminals or the VMS Mail Utility (MAIL). 


You can also add qualifiers to the DOCUMENT command to create indexes, 
master indexes, tables of contents, and to modify the default processing of 
your input file. The DOCUMENT command, parameters, and qualifiers, 
are explained in Appendix A. Chapter 4 discusses various processing tasks 
accomplished by using the command line. 





1.5 Types of Documents 


One of .most powerful features of VAX DOCUMENT is its ability to format 
the same input file into a variety of document types (doctypes). The standard 
doctypes offered with the product cover a range of documentation needs. 
For VAX DOCUMENT Version 1.1, there are seven supported doctypes (see 
Table 1-1). Also, most doctypes offer more than one design. The doctypes 
are explained fully in the VAX DOCUMENT User Manual, Volume 2. 


In Table 1-1, the first design listed for each doctype is the default design. It 
is designated when you type the doctype with no design on the DOCUMENT 
command line. For example, specifying MANUAL on the command line 
defaults to MANUAL. REFERENCE. 


Table 1-1 VAX DOCUMENT Doctypes 


Doctype 
ARTICLE 


LETTER 
MANUAL 


MILSPEC 


OVERHEADS 


REPORT 


SOFTWARE 


Design 
ARTICLE 


LETTER 


MANUAL.GUIDE 


MANUAL.PRIMER 


MANUAL.REFERENCE 


MILSPEC 


OVERHEADS 


OVERHEADS.35MM 
REPORT 
REPORT.TWOCOL 
SOFTWARE.BROCHURE 
SOFTWARE.GUIDE 
SOFTWARE.HANDBOOK 
SOFTWARE.POCKET_ 


REFERENCE 
SOFTWARE.REFERENCE 


SOFTWARE.SPECIFICATION 
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Description 


Creates an article format in an 85 x 11 inch format, with 
two columns for text. 


Creates memos and letters. 


Creates a user manual in a 7 x 9 inch trim size with 
numbered headings; it is intended for chapter-oriented 
tutorial material. 


Creates a user manual in a 7 x 9 inch trim size with 
unnumbered headings; it is intended for chapter-oriented 
primer material. 


Creates a user manual in an 85 x 11 inch trim size with 
numbered headings; it is intended for reference material. 


Offers a full implementation of the United States 
Department of Defense Military Specification Standard 
MIL-STD-490A and MIL-STD-2167. It accepts the full 
range of VAX DOCUMENT global tags, with the exception 
of the tags used to create part pages. 


Creates a page with an 85 x 11 inch trim size. It can be 
used to create slides that fit on overhead projectors, or 
figures that fit into an 85 x 11 inch notebook. 


Creates a 65 x 55 inch format suitable for camera-ready 
copy for making 35MM slides. 


Creates general purpose documents such as reports and 
formal outlines. 


Creates a two column format of the REPORT doctype. 


Creates a brochure in a 7 x 9 inch trim size with 
unnumbered headings and sequential page numbers; it 
is intended for nonchapter-oriented material. 


Creates a users’ guide in a 7 x 9 inch trim size with 
numbered headings. 


Creates a handbook in a 7x9 inch trim size with numbered 
headings. 


Creates a pocket reference in a 55 x 7 inch trim size with 
numbered headings. 


Creates a reference manual in an 85 x 11 inch trim size 
with numbered headings. It provides various formats 
and tags for describing computer software. It is equally 
well-suited to describing information in a tutorial or in a 
reference format, and contains tags customized for use in 
describing software in either of these formats. 


Creates a specification in an 85 x 11 inch trim size with 
numbered headings. 
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1.6 Overview of the VAX DOCUMENT System 


Several integrated software tools form the components of the VAX 
DOCUMENT system. 


e The Standard DIGITAL Markup Language (SDML), used for coding 
the document files as they are written, is a generic, high-level, device- 
independent markup language. It is not concerned with formatting; the 
information it conveys is information about the logical structure of a 
document. 


¢ Three processors work on the file when you execute the DOCUMENT 
command. These processors work sequentially, checking and converting 
the generically marked text through intermediate files on its way to final 
printed form. Each file is given the same name as the original source file 
but is suffixed with the file extension specific to that processor. Table 1-2 
lists the file extensions generated by each processor. 


1.6.1 How VAX DOCUMENT Processes a File 
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When you execute the DOCUMENT command, a file is run through three 
processes: 


1 Tag translation 
2 Text formatting 


3 Device conversion 


These three processes transform your input file into formatted copy. During 
the processing of a file, you can observe the following sequence of events on 
your terminal (or, after processing, in the log file if the file was processed in 
BATCH mode). 


First, the tag translator translates the tags in the input file. As the tag 
translator processes your file, you might see error messages on the terminal. 
For example, if you misspell a tag name or fail to use an ending parenthesis, 
an error message is displayed. Processing continues so as to find as many 
errors as possible. If you have consistently misspelled a tag, you receive 

a message only for the first occurrence of that error, then a final message 
announces how many undefined tags the tag translator saw. The tag 
translator’s output is a file with the same name as the input file but a file 
type named TEX (for example, filename.TEX). 


The text formatter reads the TEX file and formats the pages of output. This 
processor might also issue error messages. The text formatter creates a file 
suffixed with the file type extension that reflects the chosen output device. 
If you specify on the command line that you want the file processed for the 
LNO3 printer, the text in the file is proportionately spaced and the DVI file 
is named DVI_LNO3. For a POSTSCRIPT device, the file is named DVI_PS. 
For a line printer, a terminal, or the VMS Mail Utility, the DVI file is named 
DVI_LINE. 


The device conversion program runs next and creates a device specific file, 
with the file type of either LN0O3, LINE, PS, TERM, or TXT. This file reflects 
the destination that you specified on the command line. In particular, if 
you specified LN03 or PS the text in the file will be proportionally spaced, 
whereas if you specified LINE, the text will be monospaced. 


1.6.2 
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The device-specific file is ready for printing (or reading on an ASCII terminal 
or mailing through the VMS Mail Utility). The file is printed automatically if 
it has been run through the three processors, unless you specified /NOPRINT 
on the command line. The file output by the device converter is printed by 
default on the device associated with the destination on the command line. 


The processors are summarized in Table 1-2. 


Table 1-2 VAX DOCUMENT Processors 





Processor 


The Tag 
Translator 


The Text 
Formatter 


The Device 
Converter 


File Types 
Created 


TEX 


DVI_LNO3, 
DVI_LINE, 
DVI_PS 


LNO3, 
LINE, 


TERM, or 
TXT 


Description 


A macro processor that translates the source files into files used by 
the text formatter. The tag translator makes two passes over the 
source file, first checking for invalid tags and then translating the 
tags. 


The text formatter reads the TEX file and formats the pages of 
output. This processor also searches for errors, but only for errors 
in the format, not in text elements or tags. Like the tag translator, 
it may issue error messages. It creates a DVI file, suffixed by the 
destination that you specified on the command line. The DVI_LINE 
file is produced for the destinations LINE, TERM, and TXT. 


As the text formatter makes up a page, it automatically formats all 
page parameters. For example, it considers the best arrangement 
of paragraphs and text elements and appends to the page the 
appropriate running head and folio. 


The device conversion program runs after the text formatter, and 
reads the .DVI_device file created by the text formatter. Whereas 
the text formatter has already made the page and line breaking 
decisions, based on the group of fonts in a given doctype, the device 
converter makes the formatted file into a printable file. 


These final output files are ready to be printed, read on an ASCII 
terminal, or mailed through the VMS Mail Utility. After processing, a 
printable file is automatically printed unless /NOPRINT was specified 
on the command line. 


Informational Messages 


Each of the processors displays an informational message when the 
DOCUMENT command is used interactively, as shown in the following 


example: 


@ $ DOCU myreport REPORT LNO3 


%DOC-I-IDENT, VAX DOCUMENT V1.1 
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Note: 


@ltag Translation]... 
“4TAG-I-DEFSLOADD, End of Loading of Tag Definitions 
“%TAG-I-ENDPASS_1, End of first pass over the input 
(Text Formatting]... 
4TEX-I-PAGESOUT, 17 pages written. 
-TEX-I-OQUTFILENAME, 'DUA1: [DOCFILES]MYREPORT.DVI_LNO3' 
[Device Conversion]... 
/%DVC-I-PAGESOUT, 18 pages written to file: 

DUA1: [DOCFILES] MYREPORT . LNO3 

[Printiag File)... 


Job MYREPORT (queue SYS$LNO3, entry 832) started on SYS$LN03 
$ 


@ Identifies the DOCUMENT command line that you type at the DCL 
prompt. In this example, the DOCUMENT command was issued for a 
file called MYREPORT.SDML, (the SDML file type is assumed by the tag 
translator). The file is to be processed for the REPORT doctype, and the 
output will be printed on the default LNO3 laser printer. 


On the command line, the command, qualifiers, and keywords can be 
abbreviated to the shortest unique string. For example, DOCUMENT 
can be abbreviated to DOCU, and the local destination, LN03..LOCAL — 
PRINTER, can be abbreviated to LNO3. . 


@ Identifies the message that indicates that the tag translator is starting to 
process the file, and will now log its activities. If there are any tag translator 
errors, they are reported at this point. 


© Identifies the point when text formatting begins. Any text formatting errors 
are seen at this point. 


© Identifies the point when device conversion begins. 


© Shows the point that the file has started printing on the specified device. 
Jobs will print by default in both interactive and batch processing. 


1.6.3 Doctype-Independent and Doctype-Specific Tags 


The majority of the SDML tags used for marking your text are valid in any 
of the doctypes. These tags are called “doctype-independent,” or “global,” as 
they work in all doctypes for which they are appropriate. For example, all 
doctypes use paragraphs and lists, so <P> and <LIST> are accepted in all 
doctypes. 


A few of the tags that are listed as global in this manual have restricted 
use, as they are not appropriate in one or more doctypes. For example, the 
doctypes LETTER or OVERHEADS do not contain front matter, such as a 
title page or preface, so the front matter tags (accepted in most doctypes) are 
restricted in these doctypes. 


Tags that are used specifically in one doctype only are called “doctype- 
specific.” For example, only a letter contains an address from the person 
sending the letter, so the doctype-specific tag <FROM—ADDRESS> can be used 
only in the LETTER doctype. 


Appendix D lists all the global and doctype-specific tags. It also identifies the 
doctype to which each doctype-specific tag belongs. 
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When first experimenting with the system, process your input file using the 
MANUAL doctype because it has no restrictions on the use of global tags. 
Later, you can experiment with the other doctypes, by reprocessing your 
SDML files and specifying the new doctype on the command line. If the 
SDML files include tags that are not recognized in the specified doctype, 
informational messages are issued, and you can either fix the errors or go 
back to using the MANUAL doctype. 


1.6.4 Context-Sensitive Tags 


Some tags are used in a group rather than individually. They are grouped 
according to function and are defined in the context of other tags. Such 
context-sensitive tags need a tag that enables the rest of the tags in that 
group. You generally place the tags in the group in a specific order, and 
terminate the ordered group with a terminating tag. For example, a table 
begins with a <TABLE> tag and ends with an <ENDTABLE> tag. Between 
these tags are additional tags that supply information about the number of 
columns, column widths, column headings; this pattern of tags is the same 
for every table. 


Other examples of global context-sensitive tags include lists, examples, and 
figures. An example of doctype-specific context-sensitive tags is the group of 
reference template tags used in the SOFTWARE doctype. 





ae Processing Books and Elements of Books 


You can use VAX DOCUMENT to process files that are individual 
components of a large book. A book is usually divided into chapters, whereas 
other types of documents are not chapter-oriented. In a book, each chapter is 
considered its own book element, and is kept in its own file. By setting up a 
book in this way, you can process the book’s chapters either separately or as 
a whole. The processing of a whole book is called a bookbuild. 


Processing a document in a nonbook format (not using a bookbuild) is 
generally useful when you have a smaller document and plan to process the 
entire document every time you make a change, and you are not concerned 
with maintaining cross-references in the book. A bookbuild allows you 

to build a large book and then process elements of it while maintaining 
cross-references. 


To perform a bookbuild, you must create a separate file that contains a list of 
all the book’s elements in the order that they will appear in the book. The 
separate file profiles the order of the book, from front to back, and hence 

is called a profile. The book’s profile becomes the main vehicle used for 
processing the book. 
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2.1 


Creating an SDML File 


Global Tags 


This chapter provides guidelines for creating an SDML file with VAX 
DOCUMENT. It explains the use of the various types of code in an SDML 
file, including tags and arguments. The principal rules of coding syntax 
are also explained. The use of these rules permits VAX DOCUMENT'’s tag 
translator to recognize and act on the tags that mark your text. 





In all files generically coded with VAX DOCUMENT, text must be marked, 
or “tagged,” so that the text is formatted correctly when the file is processed. 
For every text element (that is, every individually treated portion of text), you 
insert a unique ASCII character sequence to identify that type of text element. 
These character sequences identify a paragraph as a paragraph, a table as a 
table, and so on. 


Tags are used to identify the text elements. A tag is a term or abbreviation 
enclosed in angle brackets (<...> ). When VAX DOCUMENT processes your 
SDML file, it recognizes the tags, translates them, and formats the text. 


There are three rules concerning VAX DOCUMENT use. 


RULE #1: 


Type each tag as shown, adding no punctuation or spaces. Use angle brackets 
to enclose tags. The tag name may be in uppercase or lowercase letters, or a 
combination of both. 


Here are some sample tag formats: 


Tag Format Function 

<P> Starts a paragraph 

<CHAPTER> Marks the beginning of a chapter and specifies its title 
<TABLE> Starts a table (like this one) 

<NOTE> Starts text that receives distinctive treatment 
<ENDNOTE> Ends the text that receives distinctive treatment 


There are two types of tags: tags that mark the starting point of a text element 
(for example, <P>, <TABLE>, or <NOTE> ) and tags that completely 
encompass a text element (for example, <HEAD1> or <CHAPTER> ). Of the 
first type, some require explicit termination (for example, <NOTE> requires 
<ENDNOTE> ) and some do not (for example, <P>). All the text that lies — 
between the starting and terminating tags receives distinctive treatment. 


All VAX DOCUMENT global tags are listed alphabetically and described in 
Chapter 9. The description of every tag in that chapter indicates whether that 
tag requires explicit termination. . 
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2.1.1 Tag Arguments 


There are two types of tag arguments, those that provide additional 
characteristics or identify requirements of the text associated with a tag 

and those that provide actual text. Some tags require one or more arguments, 
while other tags do not require arguments but can accept them as additional 
information. Still other tags do not accept any arguments. 


An argument is enclosed in parentheses and immediately follows the closing 
angle bracket of the tag. If you use an argument with a tag that will not 
accept one, VAX DOCUMENT issues warning messages when you process 
the file. More than one argument can be included within the parentheses 
(this is called an argument list). A space or an end of line cannot separate the 
tag from its argument list. 


RULE #2: 


Supply only those arguments that are permitted by the tag’s format. Use 
parentheses to enclose arguments. 


Use a backslash (\\) to separate multiple arguments. For example, the 
<CHAPTER> tag takes two arguments, a chapter title and a symbol name 
for that title. Therefore, the title for a chapter of a book would be coded with 
a backslash, as follows: 


<CHAPTER> (Introduction to Farming\intro_farm) 


Each tag description in Chapter 9 includes a list of valid or required 
arguments to that tag. Use of symbol names is discussed in Chapter 6. 





2.2 Coding an SDML File 


RULE #3: 
Tag every text element. 


This rule is true whether or not the tag requires an argument list, a 
terminating tag, or both. 


For example, the following text contains two text elements and so requires 
two tags: 


<P>Employment opportunities grew throughout the company. If the president 
of the company had realized what a <NEWTERM>(matrix) would start 
developing... 


In this example, the writer started a new paragraph and so tagged it with the 
<P> tag. The writer also wanted to identify a new term in this document 
with some special format, so treated the term as an individual text element 
and tagged it. The output of this paragraph might appear like this: 


Employment opportunities grew throughout the company. If the president of 
the company had realized what a matrix would start 
developing... 


The three rules concerning the use of VAX DOCUMENT cover the 
requirements for coding any SDML file. By remembering these rules, you 
should be able to code your files with few errors. However, there are several 
special cases to keep in mind when you want to show coding characters, 
characters used by VAX DOCUMENT internally, in your output. The 
following discussion explains these unusual cases. 
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Special Coding in an SDML File 


VAX DOCUMENT treats certain characters and character-strings in a special 
manner when they are placed in an argument to an SDML tag. Table 2-1 
summarizes these characters and how to correctly code them. 


Table 2—1 Coding Special Characters 


Character 
<text> 


<P> ( 


USER$: <SMITH> 


— 


— 


— 


(eo 


Placement of Character Correct Coding in Text 
Angle brackets enclose a tag <LITERAL> ( <text> ) 
name not meant to be translated 

as a tag. 


Opening parenthesis following a Leave space between the closing angle bracket 
tag which accepts no arguments. (> ) and the opening parenthesis (() of the tag. 


Angle brackets enclose a file <FILE_SPEC> (USER$: <SMITH> ) 
specification not meant to 

be translated as a tag in an 

argument. 


Unmatched opening parenthesis <OPAREN> 
in an argument. 


Unmatched closing parenthesis in <CPAREN> 
an argument. 


Backslash in an argument. <BACKSLASH> 
Vertical bar in an argument. <VBAR> 
Ampersand in an argument. <AMPERSAND> 


The tag translator displays a message when you have incorrectly coded any of 
these special characters in an argument. The correct coding of each of these. 
characters is explained in detail in the following sections. 


Two other special cases are also discussed in this section: Section 2.3.6 
discusses how to code a hyphen in text, and Section 2.3.7 discusses the usage 
of tabs in SDML files. 


Coding Text That Looks Like a Tag 


When a word is surrounded by angle brackets, the tag translator attempts to 
evaluate it as a tag. If it is a valid tag, it is translated like any other tag; if it 
is not a valid tag, a warning message is issued when the file is processed, and 
the word, enclosed in angle brackets, is placed in the output unchanged. 


For example, the following text contains the terms <reroute> and 
<return> , coded as if they are tags: 


<P>When marking packages for delivery, do not confuse the 
<reroute> destination with the <return> destination. 


During processing, the tag translator tries to translate these terms as tags. It 
produces two warning messages because <reroute> and <return> are 
not defined as valid tags. 
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Note: 


To avoid this problem, use the <LITERAL> tag, which directs the tag 
translator to ignore everything (including the angle bracket characters) in 

its argument. To have <reroute> and <return> appear in the text but 
not generate warning messages, the above example should be coded like this: 


<P>When marking packages for delivery, do not confuse the 
<LITERAL>(<reroute>) destination with the 
<LITERAL>(<return>) destination. 


Notice that the entire term that you want to include in the text, including the 
angle brackets, is treated as an argument to the <LITERAL> tag. 


Use the <LITERAL> tag to document any characters that are prefixed with 
angle brackets. For example, the control characters of the ASCII character set 
commonly are surrounded by angle brackets, such as <STX> or <NAC>. 
Another case where you might show an angle bracket is in an equation. For 
instance, in the equation “If M <P then ...,” the tag translator tries to define 
this as part of the paragraph tag ( <P> ), and issues a warning. 


You can place a single angle bracket anywhere in the file, as long as the 
next few characters do not look like they begin a tag. If they do look 
like tags to the tag translator but are not valid tags, you will receive 

a warning message. Coding the angle bracket within a <LITERAL> 


argument ( <LITERAL> ( <)) ensures that you will not receive a warning 


message for placing a single angle bracket in a file. 


2.3.2 ‘Coding File Specifications That Include Angle Brackets as 


Arguments 


VAX DOCUMENT provides several tags that allow you to include separate 
files into your SDML file; such tags require a file specification argument to 
access an external file. Because the directory portion of a file specification can 
be delimited with angle brackets, and so resemble a tag in these arguments, 
such file specifications must receive special treatment. 


Use the <FILE_SPEC> tag to designate a file specification that contains angle 
brackets as the file-spec argument to an SDML file-inclusion tag. 


For example, to include the file <SMITH> picture.sixel into a figure and not 
have VAX DOCUMENT translate <SMITH> as a tag, you would use the 
<FILE_SPEC> tag as follows: 


<F IGURE_FILE>(LNO3\<FILE_SPEC>(<smith>picture.sixel) \20) 


The following SDML tags let you include external files, and so are the only 
tags that might require the use of the <FILE_SPEC> tag in an argument: 


e <ELEMENT> 

bd <EXAMPLE_FILE> 
s <FIGURE_FILE> 

bd <ICON_FILE> 

bd <INCLUDE> 

© <INCLUDES_FILE> 


° <TABLE_FILE> 
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Section 2.3.1 lists the ways in which you can code file specifications that 
appear in text and not as file-spec arguments to tags. 


2.3.3 Coding Opening and Closing Parentheses in an Argument 


When the closing angle bracket of a tag is followed immediately by an 
opening parenthesis, the tag translator assumes that an argument follows. 
The tag translator reads the argument, looking for a matching closing 
parenthesis to mark its end. If one of your arguments includes an unmatched 
closing parenthesis, the parenthesis will be mistaken for the end of the 
argument. 


If an argument needs to include an unmatched opening or closing parenthesis, 
you can code it with special tags created for this purpose. Use either 

the <OPAREN> (that is, opening parenthesis) or the <CPAREN> (closing 
parenthesis) tag. A parenthesis that is coded this way is not matched with its 
counterpart by the tag translator. It does not disturb the counting of matched 
pairs of parentheses, nor the recognition of the true end of the argument list. 
For example: 


<HEAD1>(A (CLOSE Statement) 
must be coded as: 
<HEAD1>(A <OPAREN>CLOSE Statement) 


Outside of an argument, parentheses cause no problems. For example, the 
following line is coded correctly: 


<P>We always use a (CLOSE Statement in the code... 


You need only use the <OPAREN> and <CPAREN> tags within arguments 
because parenthesis characters have no special meaning outside of arguments. 
For more information on <OPAREN> and <CPAREN> , refer to the tag 
descriptions in Chapter 9. 


Note: Open parentheses following tags that do not accept arguments must be 
preceded by one or more blank spaces. For example, in the following code 
a space must be placed after the <P> tag, or the text in the parentheses 
must be placed on a new line. 


<P> 
(See Section X.) 


2.3.4 Coding a Backslash in an Argument 


A backslash is used to separate arguments. If you want to include a 
backslash character within one of your arguments, you must code it using 
the <BACKSLASH> tag. Otherwise, the backslash in your argument is 
interpreted as an argument separator. In effect, the tag translator will make 
two arguments out of what you perceive as one argument. For example: 


<P>Insert the part numbered <KEYWORD>(ABC\123) into 


The tag translator treats this as two arguments and issues an error message 
because this tag cannot accept two arguments. To include a backslash that 
will not be evaluated by VAX DOCUMENT, write the following: 


<P>Insert the part numbered <KEYWORD>(ABC<BACKSLASH>123) 
into 
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The following is produced: 
Insert the part numbered ABC\123 into 


You need to use this special coding only within arguments. For more 
information on <BACKSLASH> , refer to its description in Chapter 9. 


2.3.5 Coding a Vertical Bar or Ampersand in an Argument 


The tag translator assigns special meanings to the vertical bar (!) and the 
ampersand (&) characters, recognizing them as a pair of internal coding 
characters. When the tag translator is reading an argument list and finds a 
vertical bar, it starts looking for a matching ampersand. 


Because these tags have special meaning within argument lists, you should 
code the vertical bar character with the <VBAR> tag and the ampersand 
character with <AMPERSAND> within your arguments. You need do this 
only within arguments, however, because these characters have no special 
meaning outside of arguments. 


The following example that shows the difference between using an 
ampersand in a tag argument and using it in text: 


<HEAD3>(The Ampersand (<AMPERSAND>) Character) 


<P>The ampersand character (&) is used to continue a BASIC 
statement on the next line... . 


Within the argument to the <HEAD3> tag, the ampersand must be coded 
with the <AMPERSAND> tag. In the text, the ampersand can be coded with 
the ampersand character. 


2.3.6 Coding a Hyphen in Text 
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When two or three hyphens are used consecutively in proportionally-spaced 
text, VAX DOCUMENT translates them into en dashes and em dashes. (An 
en dash is slightly longer than a hyphen, and an em dash is slightly longer 
than an en dash.) This does not occur in monospaced text, such as text in 
examples. Table 2-2 illustrates how to code a hyphen, an en dash, an em 
dash, and a minus sign in text and gives an example of each use. 


Table 2—2 How to Code a Hyphen in Text 


Character Sample of Result of 

Produced SDML coding SDML coding 

hyphen two-column two-column 

en dash 1981--1983 1981-1983 

em dash! That is -- what I mean to say | That is—what | mean to say 
em dash' That is---what I mean to say | That is—what | mean to say 
minus sign <MATH> (a<MINUS>b) a—b 


‘An em dash may be produced either by using three consecutive hyphens with no 
space on either side of them, or by two consecutive hyphens with space on each 
side of the hyphens. Two consecutive hyphens without spaces surrounding them 
will produce an en dash. 
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2.3.7 Coding Tab Characters in Text 


VAX DOCUMENT processes tab characters in an SDML file into spaces. For 
example, if you had pressed the TAB key three consecutive times to insert 
space into your SDML file, VAX DOCUMENT would interpret the three tabs 
as three spaces, but would output them differently depending on whether the 
three spaces occurred in monospaced or proportionally-spaced text. 


If those three tabs occurred in a monospaced example (for example, within 
<CODE_EXAMPLE> and <ENDCODE_EXAMPLE> ), they would be output as 
three spaces; however if they occurred in proportionally-spaced text (for 
example, within a paragraph), then the three spaces would be replaced by a 
single space. 


Generally, you should avoid using the TAB key in order to eliminate 
confusion about the spacing in the SDML file; however, entering tabs into an 
SDML file is not invalid. 
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Paragraphs 


This chapter discusses the coding of text elements frequently used in almost 
every doctype. These text elements include the following: 


e Paragraphs 


© Headings 


¢ Chapters 


e¢ Front Matter text elements, including title page, copyright page, and 
preface 


e¢ Back Matter elements, including appendixes and glossary 


e —_ Lists 
e Tables 
e Figures 


e Examples 


This chapter describes some of the most basic tags used in any doctype within 
VAX DOCUMENT. The tags are also described in Chapter 9. 





A paragraph is labeled with the <P> tag. Within a doctype, the tag 
creates the same output, no matter where it is placed in a document. It is 
unnecessary to leave blank lines before or after the paragraph, or to recall any 
of the other usual formatting conventions required when a typewriter is used. 
For example, spacing, justification, and indention of a paragraph are provided 
by the specified doctype. As writer, you must only inform the text processor 
that you want this specific text element. Anywhere you place a <P> tag, the 
text processor will begin a new paragraph. The only reason that you might 
want to leave blank lines or spaces in your file is to make it easier to read 
your source file. 


The following example shows the use of the <P> tag in a doctype that calls 
for space between paragraphs, with no indentation. 


<P>The species is the basic unit of classification. Clearly, 

not all species resemble each other to the same degree or 

are closely related. <P>In any careful study, 

one of the vital early steps is the organization and naming of objects. 


Output 


The species is the basic unit of classification. Clearly, not all species 
resemble each other to the same degree or are closely related. 


In any careful study, one of the vital early steps is the organization 
and naming of objects. 


Note that the paragraphs are formatted correctly no matter how your source 
file is broken across lines. 
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If you want a paragraph enclosed in parentheses, be careful to place a space 
or an end of line between the tag <P> and the parenthetical text. For 
example: 


The species is the basic unit of classification. 
<p> (Clearly, not all species resemble each other to the same degree or 
are closely related.) 








Headings 
Headings are intended to label a section of text. Depending on the 
doctype, headings can be numbered automatically during processing. VAX 
DOCUMENT keeps a count of each heading level and consecutively numbers 
each heading within a level. 
A first level heading is labeled with the tag <HEAD1> and the output is in 
the form x.x. In the same way, a second level head is labeled with the tag 
<HEAD2>. You can use up to six heading levels, as required. 
The number of a chapter is not counted as a heading level. If the document 
has a <CHAPTER> tag, the chapter number is included in the heading level 
number. For example, this chapter is number 3, and so the heading level 
number of this section became 3.2. If there is no <CHAPTER> tag, only the 
heading level number is used. 
Example 
<HEAD1>(Physical Features) 
<P>Alaska consists of a compact central mass 
<HEAD2>(General Physiographic Features) 
<P>The main features are mountains 
<HEAD3>(Physiographic Features) 
<P>Between the Pacific and Rocky Mountain systems 
This example shows the use of the <HEADx> tag for creating three heading 
levels. To see the output of this example, refer to the MANUAL doctype 
chapter in VAX DOCUMENT Design Samples. 

Chapters 


3-2 


The <CHAPTER> tag is used to label the chapter title at the beginning of a 
new chapter. If a source file contains a chapter in a book, the <CHAPTER> 
tag must be the first tag in the file, as it enables all cross-references within . 
that file. The tag requires a chaper-title as its first argument. It can accept a 
symbol-name (for the chapter-title) as its second argument and requires one if 
the file is used in a bookbuild. 


A chapter is a basic text element in many types of documentation. However, 
it is treated as a book element during a bookbuild. You can make chapters 
of a book number correctly during processing only if the chapter is listed as 
a book element in the book’s profile, and the profile is processed through a 
bookbuild procedure. An example of the beginning of a chapter follows: 


<CHAPTER> (Introduction to VAX DOCUMENT) 


In this example the chapter tag has one argument, the title for that chapter. 
The first chapter tag in a book automatically receives the chapter number 1, 
and each following chapter is incremented by one. 
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If you prefer to maintain a document in a single source file, you can include 
more than one chapter in a file, and therefore more than one <CHAPTER> 
tag. The chapters are still numbered automatically. However, you would 
have to move any chapter manually if you want to reorganize the document. 





Front Matter 


Title Page 


The front matter of a book typically consists of four components: 
e The title page 

e The copyright page 

e The table of contents (discussed in Chapter 7) 

e The preface 


The profile for your book should name a single book element as the front 
matter. This book element file might contain all the front matter material or 
it might use the <INCLUDE> tag to bring in separate SDML files containing 
front matter material, such as the title page, copyright page and preface. 


The following is an example of front matter in a single SDML file: 


<FRONT_MATTER> (front) 
<TITLE_PAGE> 

<TITLE>(User Manual, Volume 1) 
<ORDER_NUMBER> (11-222-333) 
<ENDTITLE_PAGE> 


<COPYRIGHT_PAGE> 
<PRINT_DATE>(August 1988) 
<COPYRIGHT_DATE> (1988) 
<ENDCOPYRIGHT_PAGE> 


<CONTENTS_FILE> 


<PREFACE> (11) 
<PREFACE_SECTION>(Intended Audience) 


<PREFACE_SECTION>(New and Changed Features) 


<ENDPREF ACE> 
<ENDFRONT_MATTER> 


The title page is produced by a group of context-sensitive tags. The title page 
consists of the following tags: 


<TITLE_PAGE> 
<TITLE>(... ) 
<ORDER_NUMBER>( ... ) 
<ABSTRACT> 


<ENDABSTRACT> 
<REVISION_INFO>( ... ) 


<ENDTITLE_PAGE> 
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3.4.2 Copyright Page 


3.4.3 Preface 


The <TITLE_PAGE> tag is defined only within the context of the 
<FRONT_MATTER> tag. The title page of this book illustrates the output of - 
each of the tags. 


The copyright page is produced by a group of context-sensitive tags. The 
copyright page tags include: 


<COPYRIGHT_PAGE> 
<PRINT_DATE>( ... ) 
<COPYRIGHT_DATE>(... ) 

<ENDCOPYRIGHT_PAGE> 


The <COPYRIGHT_PAGE> tag is defined only within the <FRONT_MATTER> 
tag. The copyright page of this book illustrates the output of each of the tags. 


The <PREFACE> tag is defined only within the front matter. The preface 
pages of this book illustrate the type of output these tags produce for this 
book’s doctype and destination. 


The preface always begins on a right-hand page following the table of 
contents, thus it always begins with an odd page number. However, because 
the table of contents is produced separately from the rest of the book, VAX 
DOCUMENT cannot automatically supply the correct starting page number 
for the preface. 


When you are doing a final bookbuild, you must determine the actual number 
of pages in the table of contents and then, if necessary, edit the file that 
contains the preface, supplying the desired page number as an argument to 
the <PREFACE> tag. 


Calculate the preface page number by adding two to the number of pages 

in the table of contents, to account for the title and copyright pages. If this 
number is even, add one to it and use the result as the argument to the 
<PREFACE> tag. For example, if the table of contents requires six pages, the 
first part of the calculation yields eight, an even number. Add one and use 
nine as the argument to the <PREFACE> tag. However, if the sum of two 
plus the number of pages in the table of contents is odd, add two to the result 
to obtain the next highest odd number. Then reprocess the front matter with 
the DOCUMENT command to obtain front matter output that displays the 
correct page numbers. 





3.5 Back Matter 
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The back matter of a book can consist of the following: 
e Appendixes 
¢ Glossary 


e¢ Index (discussed in Chapter 7) 


3.5.1 


Appendixes 


3.5.2 Glossary 


3.6 


Lists 
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Appendixes are structured exactly the same as chapters. They consist of 
hierarchically numbered sections containing paragraphs, illustrations, and 
so forth. Use the <APPENDIX> and <ENDAPPENDIX> tags to enclose each 
appendix. Appendixes are automatically given sequence letters in the order 
corresponding to the order in which they appear relative to one another in 
the bookbuild. Thus, you need to give your appendixes symbolic names so 
that you can refer to them in the book. 





The glossary is a simple structure that is produced using a template. The 
glossary template consists of the following pattern of tags: 


<GLOSSARY> (Glossary\gloss_chap) 


<GTERM>(... ) <GDEF>(... ) 
<GTERM>( ... ) <GDEF>(... ) 
<ENDGLOSSARY> 


The glossary begins automatically on a right-hand page with a proper 
heading. You should arrange glossary terms alphabetically. 





There are several types of lists: 


ALPHABETIC The list element identifiers are alphabetic letters. 

CALLOUT The list element identifiers are reverse-print callout numbers 
(on supported output devices), for example ©. 

NUMBERED The list element identifiers are arabic numerals. 

ROMAN The list element identifiers are roman numerals. 

SIMPLE There are no list element identifiers. 

STACKED List elements do not have identifiers, but are stacked within 
the specified set of delimiters (braces, brackets, or double 
brackets). 

UNNUMBERED List element identifiers are special characters, such as bullets. 


The following tags are needed to create any type of list: 
e <LIST> (with a required argument that specifies the type of list) 
e <LE> (meaning “list element”) 


® <ENDLIST> 


The following example shows the use of the <LIST> tag to create an 
unnumbered list. 
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Example 

<P>Mammalian classification of the order Lagomorpha follows: 
<LIST> (UNNUMBERED) 

<LE>Kingdom Animal 

<LE>Phylum Chordata 

<LE>Class Mammalia 

<LE>Order Lagomorpha 
<LE>Family Leporidae 

<LE>Genus Lepus 

<LE>Species Lepus californicus 
<ENDLIST> 


Output 

Mammalian classification of the order Lagomorpha follows: 
¢ Kingdom Animal 

¢ Phylum Chordata 

¢ Class Mammalia 

e Order Lagomorpha 

e Family Leporidae 

e Genus Lepus 


e Species Lepus californicus 


As shown in this example, a <LIST> tag requires a terminating tag, 
<ENDLIST>. The <ENDLIST> tag terminates any type of list and does 
not require an argument. 


The <LE> tag identifies each element within the list. 





3.7 Tables 


The <TABLE> tag is used to create both informal and formal tables. The two 
types of tables differ in the following ways: 


Informal Given no caption, is unnumbered and is not listed in the table 
of contents. 


Formal Given a caption and numbered. Listed in the table of contents. 
Can be referenced with the <REFERENCE> tag. 


Only four tags are required to create either type of table: 
e <TABLE> 

bd <TABLE_SETUP> 

e = <TABLE_ROW> 


® <ENDTABLE> 


Table 3-1 describes the four required tags. It also describes several other 
tags that are not required to create a table but are useful to specify special 
formatting. Table 3-1 lists the tags in the order that they should be used in 
your SDML file. Note that the <TABLE_ROW> tag can be used throughout 
a table. In Table 3-1, arguments are not shown for any tag except for the 
<TABLE> and <TABLE_ROW_BREAK> tags. 


Table 3-1 Table Tags 
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Tag, in order of use 
<TABLE> (table-caption\symbol-name) 


<TABLE_ATTRIBUTES> 


<TABLE_SETUP> 


<TABLE_HEADS> 
<TABLE_ROW> 


<TABLE_ROW_BREAK> (first) 
<TABLE_ROW-_BREAK> (last) 


<VALID_TABLE_ROW_BREAK> 


<ENDTABLE> 


Description 


Creates a table and enables all other table tags. The optional 
symbol-name argument can be used to reference the table. ' 


Specifies special formatting for the table, such as wide, multipage, 
or a table that is not to be broken between pages. The table’s 
attributes are ignored if this tag does not precede <TABLE 
SETUP> . 


Establishes, or “sets up,” the number of columns in the table and 
the table width. If excluded, the table will not be created. You 
always list each column width except for the width of the last 
column. 


_ Specifies headings for the table columns. 


Specifies text for one row of the table. Each argument supplies 
the text for a column in a row. Can precede or follow table units 
(grouped sections of the table) as required. Can be repeated 
throughout the sequence of table tags. 


Specify the boundaries within which a table can be broken onto 
a new page. Not required, but useful for controlling the format of 
the table. 


Controls the pagination of long table rows. Required in tables with 
long table rows. 


Terminates <TABLE>. 


‘In the <tTaste> tag, the table-caption argument is required in a first level formal table, but is not permitted 
in a nested table (a table embedded in another table). 





A second group of table tags exists to perform special table functions. For 
example, you can embed a heading in a table that spans several of the table’s 
columns, or you can embed a table within another table. These special 

tags are not required to create a table, but are available for more complex 
formatting needs. 


Table 3-2 lists the special table functions available, the tags required for each 
function, and the location where an example of each function can be found in 


Chapter 9. 
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Table 3—2 Special Table Functions 





Function 


Aligning numbers in 
a table. 


Nesting (embedding) 
a table within 
another table. 


Creating a table key 
(legend) to explain 
abbreviations used in 
the table. 


Embedding a 
heading in a table 
that spans the length 
of several table 
columns. 


Grouping sections of 
a table and labeling 
the sections. 


Including in the 
source file a 
separate file that 
contains a table. 


Tags Used 
<ALIGN_CHAR> 


All table tags are used. 
<NESTED_TABLE_— 
BREAK> is required. 


<TABLE_KEY > 


<ENDTABLE_KEY > 


<TABLE_KEYREF > 


<SPAN> 


<RULE> 


<TABLE_UNIT> 


<TABLE_UNIT_HEADS> 


<ENDTABLE_UNIT> 


<TABLE_FILE> 


Tag Description 


Specifies a special character 
that is replaced by a space 
wherever it appears in table 
rows. The character can 
be used to achieve vertical 
alignment within a column. 


Marks a place that a nested 
table may be broken across 
pages. 


Begins a key for the table. If 
used, it must follow <TABLE_ 
SETUP> . 


Terminates the <TABLE_ 
KEY> tag. 


Specifies that the table key 
or legend should be printed 
below the table. Required if a 
table key or legend is included 
in the table. 


Causes a heading to span 
more than one table column. 


Specifies that a horizontal 
rule should appear below the 
embedded heading. 


Divides a table into groups. 
The groups can have headings 
within the table. 


Specifies the table unit 
headings. If used, must 
follow <TABLE_UNIT> . 


Terminates the <TABLE 
UNIT> tag. 


“Includes a separate file which 


contains a table. Not required. 


Location of Example 
of Function in 
Chapter 9 


See <ALIGN_CHAR> 


See <NESTED_TABLE_ 
BREAK> 


See <TABLE_KEY> 


See <TABLE_UNIT> 


See <TABLE_UNIT> 


See <TABLE_FILE> 
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Location of Example 
of Function in 


Function Tags Used Tag Description Chapter 9 
Referring to the <REFERENCE> If a symbol-name is specified See <REFERENCE> 
symbol-name given ina <TABLE> tag, this tag 

to the table. can be used to reference the 


symbol name in other places 
in the document, thereby 
always producing the correct 
table number and caption. 


Example 


<P>See <REFERENCE>(heart_rate_tab) for a list of 
the heart rates of selected mammals. 


<TABLE>(Heart Rates of Selected Mammals\heart_rate_tab) 
<TABLE_ATTRIBUTES> (keep) 

<TABLE_SETUP> (3\19\16) 

<TABLE_HEADS> (Common Name\Weight\Heart Rate, Beats per Minute) 
<TABLE_ROW> (European hedgehog\500-700 g.\246) 
<TABLE_ROW>(Gray shrew\3-4 g.\782) 

<TABLE_ROW>(Least chipmunk\40 g.\684) 

<TABLE_ROW> (Gray squirrel\500-600 g.\390) 

<TABLE_ROW> (Harbor porpoise\170 kg.\40-110) 

<TABLE_ROW> (Mink\0.7-1.4 kg.\272) 

<TABLE_ROW> (Harbor seal\20-25 kg. \18-25) 

<ENDTABLE> 


The output of this example follows: 
Output 


See Table x—x for a list of the heart rates of selected mammals. 


Table x—x Heart Rates of Selected Mammals 


Heart Rate, Beats per 


Common Name Weight Minute 
European hedgehog 500-700 g. 246 
Gray shrew 3-4 g. 782 
Least chipmunk 40 g. 684 
Gray squirrel 500-600 g. 390 
Harbor porpoise 170 kg. 40-110 
Mink 0.7-1.4 kg. 272 
Harbor seal 20-25 kg. 18-25 





3.7.1 Controlling Table Attributes 
You can control the following attributes of tables: 
e Formality (that is, if the table has a number and a caption or not) 


e Its overall width and the size of the text 
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e Whether it is allowed to break across pages or if the entire table must be 
kept on a single page 


The formality is controlled by the presence of the caption argument in the 
<TABLE> tag. If you do not specify this argument, no number is assigned to 
the table. Tables are automatically numbered. The numbers are sequential 
throughout a document, or numbered beginning at 1 in each chapter. 

With the exception of the REPORT document type, you cannot control 

the numbering; that is an attribute of the overall document type and design. 


You have control over the table attributes of width (the table’s margins) and 
page-breaking. These two attributes are discussed in the following sections. 


Controlling a Table’s Margins 
The width of a table, that is the left and right margins, is determined by the 
following default attributes: 


e For formal tables, the left margin of the table is, by default, the same as 
the normal left margin of text, regardless of whether the text immediately 
preceding the table is indented. 


e For informal tables, the left margin of the table is the same as the current 
left margin of the text. If the text is indented, (for example if it is a list 
element) the table is indented at the same margin. 


e In either case, the right margin of the table is always the same as the 
right margin of the text. 


For example, if you coded Table x-x without arguments to the <TABLE> tag, 
and in the context of a list, it would be output as follows: 


Output 


e These are the heart rates: 


Common Name Weight Heart Rate, Beats per Minute 
European hedgehog 500-700 246 

Gray shrew 3-4 g. 782 

Least chipmunk 40 g. 684 

Harbor porpoise 170 kg. 40-110 

Mink 0.7-1.4 kg 272 

Harbor seal 20-25 kg. 18-25 


If you specify table width values that extend the table beyond the right 
margin of text, the following actions occur: 


e The text formatter makes an attempt to switch the size of the text in the 
table to a smaller size to see if the table will fit. 


e If the table still does not fit, the text formatter issues a warning message; 
the device converter normally issues a message also. These messages 
alert you that you must make some adjustments in your table. 


In many cases, you can lower the width values to the <TABLE_SETUP> tag to 
reduce the widths of the individual columns. 


Common Name 
European hedgehog 


Least chipmunk 
Harbor porpoise 
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In some doctype designs, there is a wide left margin. In those doctypes, 
the keyword attribute WIDE to the <TABLE_ATTRIBUTES> tag tells the text 
formatter to use the full page width for the table. Here is the same table 
coded with <TABLE_ATTRIBUTES> (WIDE): 


Weight Heart Rate, Beats per Minute 
500-700 246 

3-4 g. 782 

40g. 684 

170 kg. 40-110 


0.7-1.4kg 272 
20-25 kg. 18-25 





The <TABLE_ATTRIBUTES> tag, if specified, must precede the <TABLE_ 
SETUP> tag in your SDML file. 


You can use the attribute WIDE to avoid having the text formatter switch 
to a smaller text size. If you require the smaller text size, you can specify 
<TABLE_ATTRIBUTES> (MAXIMUM). 


Controlling Page Breaks in Tables 

One of VAX DOCUMENT’s more powerful features is its ability to handle 
long tables, that is, tables that require more than a page of output. By default, 
when the text of a table does not fit on a single page, VAX DOCUMENT 
assumes that it can break the table across pages, and prints as much of the 
table as it can on each page. 


When a table is continued across several pages, the text formatter repeats the 
following text at the top of the second page and each subsequent page of 
output: 


e The table number and caption (with the text “Cont’d”) if the table is a 
formal table! 


e The table column headings, if any 


If a table is short and you want to keep it on a single page, you can specify 
<TABLE_ATTRIBUTES> (KEEP). In this case, the text formatter determines if the 
table fits on the current page. If the table does not fit, the text formatter starts 
a new page of output, leaving the page pecaue the table short, that is, with 

blank space at the bottom. 


You can control the page breaks in multipage tables in several ways: 


e Use both the <TABLE_ROW_BREAK> (FIRST) and <TABLE_ROW_ 
BREAK> (LAST) tags to indicate good first and last places at which page 
breaks are allowed. 


e Group sequences of table rows that must be kept together using the 
<TABLE_UNIT> tag. 


In some cases, you may also need to provide special information to the text 
formatter to help in breaking complex tables. 


1 The continued caption’s placement and the continuation text may vary from one doctype to another. 
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The following list summarizes the rules for breaking tables. If you are having 
difficulty getting a table to come out correctly, review these rules to see what 
you might need to do. 


Rules for Page Breaking in Tables 
The following list gives some basic rules for page breaking within tables. 


¢  <TABLE_ROW_BREAK> (first) specifies the first place within a table at 
which a page break is acceptable. You can choose this based on the text 
in the table rows themselves. For example, if each row in the table has 
only a single line of text, you would probably place the <TABLE_ROW_ 
BREAK> (first) tag after 3 or more <TABLE_ROW> tags. On the other 
hand, if each row in the table (or even just the first) has ten or more lines 
of text, you might want to allow breaking after the first row. 


¢ <TABLE_ROW_BREAK> (last) specifies the last place within a table at which 
a page break is acceptable. 


e Between these two tags, the text formatter assumes that it is okay to break 
the table between any two table rows. It assumes that all text before the 
first place and after the last place must be on the same page. If the text 
before the first place or after the last place is more than a page, the text 
formatter chooses a place to break the table anyway. 


e If you do not specify these tags, the text formatter first tries to keep the 
entire table on one page. If the table does not fit, it breaks the table 
anyway, fitting as much as it can on each page. 


e By default, all table rows within the bounds of a table unit are places 
where page breaks must not occur. Therefore, the text formatter will 
always try to keep all the rows in a table unit on the same page. If the 
table unit does not fit on the page, it breaks the table anyway, fitting 
as much as it can on each page. Within the bounds of <TABLE_UNIT> 
and <ENDTABLE_UNIT> , you can specify <TABLE_ROW_BREAK> (FIRST) 
and <TABLE_ROW_BREAK> (LAST) tags to indicate the best first and last 
places, as in the table itself. 


e Ifa table has footnotes, the text formatter does all the page breaking. The 
<TABLE_ROW_BREAK> tags are ignored. 


e By default, the text formatter never breaks a table in the middle of a table 
row. Consider the following example of a table row: 


(this text may be 
a half-page or more 
in length. ) 


Because the text formatter always tries to keep this table row on the same 
page, you might get short, uneven pages. If you want to allow page 
breaks within a table row, use the <VALID_TABLE_ROW_BREAK> tag in the 
middle of the column of the table row: 


<table_row>(column 1 text \ column 2 text 
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You should generally put the <VALID_TABLE_ROW_BREAK> tag 
immediately before a <P>, <LIST>, or <LE> tag. The <VALID_TABLE— 
ROW_BREAK> tag is valid only in two- and three-column tables, and is 
only valid in the last column of the table. 


The text formatter’s rule about never breaking a table in the middle of a 
table row also applies if a column in a table row contains a nested table. 
For example: 


<table_row>(column 1 text \ column 2 text 


<table> 
<table_setup>(2\10) 
<table_row>(one\two 
<p> this is now text in a nested table. 


Sometimes this text gets long, too.) 
<endtable> 
) 
To specify that it is allowable to break a page within this nested table, 
you must use the <NESTED_TABLE_BREAK> tag. This tag should be 
placed just before <P> or <LE> tags, where there is already some 
vertical space. For example: 


<table_row>(column i text \ column 2 text 


<table> 
<table_setup>(2\10) 
<table_row>(one\two 
<p> this is now text in a nested table. 


Sometimes this text gets long, too. 
<nested_table_break> 

<p>Here is some more text for this 
column. 


) 
<endtable> 
) Fe 
The more places you indicate acceptable page breaks in a table, the better 


the text formatter is able to select the best page breaks and not cause a lot 
of short, uneven pages. 


If you specify KEEP when you code a table tag, the text formatter tries to 
keep the table all on one page, no matter if it is too long. You receive a 
warning message that a page is too long, the device converter also issues 
an error message, and the part of the table that did not fit on the page 
probably will not print in the output. 


Use the <PAGE> or <FINAL_CLEANUP> (PAGE_BREAK) tags in tables 
to control paging explicitly. Note, however, that when you control page 
breaks, you might have unexpected results when you modify the input 
file for a device other than the one for which you coded the page breaks. 


Whenever the text formatter detects a possible problem, it issues an 
informational message to alert you to check your output. 
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e Use the <TABLE_ATTRIBUTES> (CONTROLLED) tag to indicate that you 


are going to explicitly specify the range in which the table will be allowed 
to break. You then must use <TABLE ROW_BREAK> (FIRST) and <TABLE_ 
ROW_BREAK> (LAST) to indicate the first and last allowable page break 
points. Between these two tags, the table may be broken between any 
two <TABLE_ROW> tags. 


° Use the <SET_TABLE_ROW_BREAK_DEFAULT> tag to provide a default 


number of rows that must be on the first page of the table. For example, 
if you specify <SET_TABLE_ROW_BREAK_DEFAULT> (3), any subsequent 
table will not be broken until after the third row. You might want to use 
this default if your table consists of single-line items. 





Use the <FIGURE> tag to indicate a text element that illustrates a point. It 
might be a graphic file, a hand-drawn illustration that you need to paste in 
your output file, or a series of keystokes that represents an item in a diagram. 


A set of required tags identifies the text as a figure, establishes the figure’s 
attributes, and identifies the end of the figure. A separate set of figure tags 
can be used to identify whether the figure is line art, an icon, located in a 
different file that you want included, or simply blank lines that you want 

inserted so that a figure can be pasted in later. 


The tags that enable the context of a figure are <FIGURE> (figure- 
caption\symbol-name) and <ENDFIGURE>. Within these two tags, you 
must include at least one tag that labels the figure text element. 


Table 3-3 summarizes the figure text element tags available for use in 
figures. 
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Table 3-3 Figure Tags 
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Function 


Including in the SDML file a 
separate file that contains a 
figure. 


Leaving blank space for a 
figure. 


Including a section of code 
as a figure. 


Including a figure that 
specifies a dialogue 
between the system and a 
user. 


Identifying a rough sketch 
produced at the keyboard 
for draft output. 


Including an illustration of 
sample text. 

Estimating a good page 
breaking point in a long 
figure. 


Referring to the symbol- 
name given to a figure. 


Tags Used 
<FIGURE_FILE> 


<FIGURE_SPACE> 


<CODE_EXAMPLE > 


<INTERACTIVE> 


<LINE_ART > 


<SAMPLE_TEXT> 


<VALID_BREAK> 


<REFERENCE > 


Description of Each Tag, 
Location of Example in Chapter 9 


Includes a figure contained in a separate file and 
1 pica of space before and after the included 
figure. See <FIGURE_FILE> . . 


Leaves a user-specified amount of space for 
a figure to be pasted in later. See <FIGURE_ 
SPACE> . wy 


Marks a section of code. See <CODE_ 
EXAMPLE> . 


Marks a system and user dialogue. See 
<INTERACTIVE> . 


Identifies the following text as fine-art. See 
<FIGURE> . 


Distinguishes an illustration of sample text from 
the surrounding text. See <SAMPLE_TEXT> . 


Indicates an acceptable page breaking point. 
Used in the context of <CODE_EXAMPLE> or 
<INTERACTIVE> . See <VALID_BREAK> . 


If a symbol-name is specified in a <FIGURE> 
tag, you can reference the symbol-name in 
other places in your document via this tag. 
See <REFERENCE> . 





Figure Elements 


When placing a figure in your input file, the tags that you use to label the 
figure as a text element must be used in the context of a <FIGURE> tag. The 
figure element (for example, a code example or a figure file) is enabled by 
<FIGURE>. The <FIGURE> tag, itself, does not include the figure element, 
but assigns the figure’s caption and the figure’s symbol-name (if used). 


Choose the figure element tag based on the type of figure. The valid tags are 
included in Table 3-3. A figure can consist of more than one type of figure 
element, and the types of figure elements can be mixed. For example, you 
can label a small graphic file and some text that accompanies it by using a 
<FIGURE_FILE> and a <SAMPLE_TEXT> tag: 


<FIGURE>(How to Load a Tape\tape_fig) 

<FIGURE_FILE>(LNO3\mydisk: [mydirectory]tape_fig.six\10) 
<SAMPLE_TEXT> 
<P>This figure illustrates how to load a tape... 
<ENDFIGURE> 


The output of this example would be a formal figure titled “How to Load a 
Tape.” The figure in [mydirectory]tape_fig.six would be included, along with 
the sample text explaining the figure. 
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3.8.2.1 


You can control the following attributes of figures: 
¢ Formality (that is, if the figure has a number and a caption or not) 
¢ The margin at which the caption is printed, if the figure has a caption 


e¢ Whether it is allowed to break across pages or if the entire figure must be 
kept on a single page, or whether it is allowed to “float” 


The formality is controlled by the presence of the caption argument in the 
<FIGURE> tag. If you do not specify this argument, no number is assigned 
to the figure. Figures are automatically numbered. The numbers may be 
sequential throughout a document, or numbered beginning at 1 in each 
chapter. With the exception of the REPORT document type, you cannot 
control the numbering; that is an attribute of the overall document type and 
design. 


The attributes that you have more control over are the margins and the 
page-breaking. These attributes are discussed in the following sections. 


Controlling a Figure’s Margins 
The width, that is the left and right margins of a figure, is determined by the 
following default attributes: 


e For formal figures, the left margin of the figure caption is the same as 
the normal left margin of text, regardless of whether the text immediately 
preceding the figure is indented. 


e For informal figures, the left margin of the figure caption is the same as 
the current left margin of the text. If the text is indented (for example, if 
it is a list element) the figure is indented at the same margin. 


The body of a figure, that is, the set of tags that specify the content of the 
figure, is processed independently of the <FIGURE> tag and its caption. For 
example, some writers use the <FIGURE> tag to formalize examples so that 
they can refer to them from anywhere in a document. For example: 


<FIGURE>(Status Message\stat_fig) 

<F IGURE_ATTRIBUTES> (WIDE) 

<CODE_EXAMPLE> (WIDE) 

%SYSTEM-S-SUCCESS, YOU HAVE SUCCESSFULLY COMPLETED ALL THE EXERCISES 
<ENDCODE_EXAMPLE> 

<ENDF IGURE> 


Here, the WIDE attribute is specified in both the <FIGURE> tag and in the 
<CODE_EXAMPLE> tag to ensure that the caption will align with the example 
text. You must use the WIDE attribute in the context of the figure’s content 
as well as in the <FIGURE_ATTRIBUTES> tag. 


3.8.2.2 
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Controlling Page Breaks in Figures 

The body of a <FIGURE> may consist of one or more individual elements; 
for instance, two or more graphics figures may comprise a single figure, 

or monospaced examples may be mixed with graphics in a figure with a 
single label. Or, a figure may consist of a monospaced example that is more 
than a page in length. In these cases, you should be aware of the rules for 
controlling page breaks in figures. 


By default, the text formatter makes the following assumptions about a figure: 
e It is less than a single page in length 


e If it is a formal figure, it is allowed to “float,” that is, if it does not fit 
immediately following its preceding text on a page, the text formatter 
moves the figure (usually to the top of the next page of output), and fills 
it in with text to avoid making a short page 


e If it is an informal figure, it is not allowed to float 


You can use the attribute keywords KEEP and MULTIPAGE in figures as 
follows: 


e KEEP tells the text formatter that you want the figure to be kept with the 
preceding text and not to float, regardless of whether a page is short 


¢ MULTIPAGE tells the text formatter that the figure has several elements 
and that page breaks are legal between the elements 


If a figure that requires more than a page is coded without the MULTIPAGE 
attribute, the text formatter issues a message and breaks the figure anyway, 
according to the following rules: 


e If the figure consists of multiple elements such as <FIGURE_SPACE> , 
<FIGURE_FILE> , and so on, the text formatter will only cause a page 
break between the individual elements. 


e If a figure consists of a monospaced example that is more than a page in 
length, the text formatter chooses page breaks based on the following: 


— Ifthe example contains <VALID_BREAK> tags, the text formatter uses 
their positions as valid page break points 


— Ifthe example contains no <VALID_BREAK> tags, but has blank lines, 
the text formatter chooses the blank lines as valid page break points 


— If the example contains neither <VALID_BREAK> tags nor blank lines, 
the text formatter puts as much text as possible on each page and 
breaks the page at the bottom 


e Use the <PAGE> or <FINAL_CLEANUP> (PAGE—BREAK) tags in figures 
to control the page breaking explicitly. Note, however, that when you 
control the page breaks, you may have unexpected results when you 
modify the input file or process the input file for a device other than the 
one for which you coded the page breaks. 
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Including Graphics Files 


Table 3-4 describes the tags that are used for including graphics in source 


files. 


Table 3—4 Tags for Including Graphics Files 


Function Tags Used to Do Function 


Enabling a small graphics <ICON> 
file to be placed to the right 
or the left of your text. 


<ICON_FILE> 


<ICON_TEXT> 


<ENDICON> 


Including in the source filea © <FIGURE_FILE> 


separate file that contains a 
figure. 





Description of Each Tag, Location of 
Example in Chapter 9 


This feature has several restrictions. Refer 
to the restrictions in the tag description. 
See <ICON>. 


Identifies the graphics file to be included 
in your text. This tag must be used in the 
context of the <ICON> and <ENDICON> 
tags. 


Accompanies an icon file with text. Must 
be used in the context of the <ICON> and 
<ENDICON> tags. 


Terminates the <ICON> tag. 


Includes a separate figure file. Valid only 
within the context of <FIGURE> and 
<ENDFIGURE> . See <FIGURE_FILE> . 


An example of how to include a figure follows: 


Example 


<FIGURE> (Keypad Illustration) 
<FIGURE_ATTRIBUTES> (Float) 


<FIGURE_FILE>(1n03\mydisk: [mydirectory] keypad.six\22) 


<FIGURE_FILE>(PS\mydisk: [mydirectory] keypad. ps\22) 


<ENDF IGURE> 


This example contains a figure file that includes another file (a graphics file) 
in this location. The tag requires the graphics file’s specification. Chapter 9 
contains full descriptions of all the figure tags, including <FIGURE_FILE> . 
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Output 


Figure x—-x Keypad Illustration 


peeee 
LILI 
LILI 
ELL 


ZK-77 15-HC 





An example is used to display an excerpt of a programming or command 
language, the interaction between a user and the system, and the like. There 
are two types of examples in VAX DOCUMENT, informal and formal. Both 
types require their own set of tags. 


The two types of examples differ in the following ways: 


Informal Remains unnumbered and is not listed in the table of contents. 


Formal Given a caption and numbered. Listed in the table of contents. 
Can be cross-referenced with the <REFERENCE> tag. 


3-19 


Using Common Tags 


3.9.1. Informal Examples 


To create an informal example, use the <CODE_EXAMPLE> and <ENDCODE_ 
EXAMPLE> tags to label your text or code excerpt. An informal example 
follows: 


Example 


<CODE_EXAMPLE> 

$! 

$! The next two lines redefine the cmd. line prompt to be the node 
$! name's initial. 

$! 

$ NODE :=='F$LOGICAL("SYS$NODE")' 

$ SET PROMPT="''F$EXTRACT(1,1,NODE)':" 

$! 

<ENDCODE_EXAMPLE> 


Output 

$! 

$! The next two lines redefine the cmd. line prompt to be the node 
$! name's initial. 

$! 


$ NODE :=='F$LOGICAL("SYS$NODE") ' 
$ SET PROMPT="''F$EXTRACT(1,1,NODE)':" 
$! 


3.9.2 Formal Examples 
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To create a formal example, use the <EXAMPLE> (example-caption\symbol- 
name) and <ENDEXAMPLE> tags to label your text. 


The example shown in the previous section could be made into a formal 
example as follows: 
Example 


<EXAMPLE> (Login Commands\login_exam) 
<CODE_EXAMPLE> 


$! 

$! The next two lines redefine the cmd. line prompt to be the node 
$! name's initial. 

$! 


$ NODE :=='F$LOGICAL("SYS$NODE") ' 

$ SET PROMPT="''F$EXTRACT(1,1,NODE)':" 
$! 

<ENDCODE_EXAMPLE> 

<ENDEXAMPLE> 


Output 


Example x—x Login Commands 





$! 

$! The next two lines redefine the cmd. line prompt to be the node 
$! name's initial. 

$! 

$ NODE :=='F$LOGICAL("SYS$NODE") ' 

$ SET PROMPT="' 'F$EXTRACT(1,1,NODE)':" 

$! 
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For the purposes of the text formatter, the <FIGURE> tags and the 
<EXAMPLE> tags are similar in function. The example and figure tags 
provide an alternate way to label (for cross-referencing purposes) a distinct 
type of example. See Section 3.8.2 for an explanation of how attributes 
are processed and how to control page breaks in multipage examples (the 
information in that section applies to both figures and examples). 


In addition to the tags listed for a formal example, you can use any of a 
second group of example tags inside a formal example to do a specialized 
function. Table 3-5 lists possible special functions and the associated tags, as 
well as the location of examples of the functions in Chapter 9. 


Table 3-5 Special Example Functions 





Function Tags 


Beginning an example of <INTERACTIVE> 


interactive dialog. 
<$> 
<U> 


Specifying a wide format <EXAMPLE_ 
for the example. ATTRIBUTES> (wide) 


Estimating a good page <VALID BREAK> 
break point in a long 


example. 


Specifying exact placement <EXAMPLE_ 
of the example on the page. ATTRIBUTES> (KEEP) 


Leaving blank space for an <EXAMPLE_SPACE > 
example. 


Including a separate <EXAMPLE_FILE> 
example file to be placed in 


your source file. 


Referring to a symbol-name <REFERENCE> 
given to an example. 


Description of Tags, Location of Example 
In Chapter 9 


Enables the <S> and <U> tags to 
distinguish system text from user text. See 
<INTERACTIVE> and <U>. 


Labels the system text of an interactive 
example. See <INTERACTIVE> . 


Labels the user text of an interactive 
example. See <INTERACTIVE> . 


Formats the example’s caption as wide. 
See <EXAMPLE> . 


Indicates an acceptable page breaking point. 
See <VALID_BREAK> . 


Specifies special formatting for the example. 
See <EXAMPLE> . 


Leaves space for an example to be pasted 
up during production. See <EXAMPLE_ 
SPACE> . 


Causes the entire contents of the specified 
file to be included in your source file. See 
<EXAMPLE_FILE> . 


If a symbol-name is specified in an 
<EXAMPLE> tag, <REFERENCE> can be 
used to reference the symbol-name in other 
places in the document, thereby always 
producing the correct example number. See 
<REFERENCE> . 
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4 Processing and Printing Files and Books 


Chapter 2 and Chapter 3 describe the basics of using the VAX DOCUMENT 

system, including how to create an input file and how to code the basic text 

elements of an input file. After you correctly code input files, the next step is 
to process the files and print or read them on various supported devices. 


Processing and printing are done by using the DOCUMENT command 
line. The components of the command line are discussed in Appendix A. 
This chapter describes the specific use of these components for processing 
an individual file or a group of files, and identifies several command line 
qualifiers used to enhance the process. 


Appendix A describes the processing commands and qualifiers that are 
available from the VAX DOCUMENT command line. 





4.1 The Four Types of Processes 


The DOCUMENT command is used to process your input files in any of four 
ways: 


e As an individual file (processed in a file build) 


You have an individual file that contains all the SDML tags required to 
create an entire document. For example, a file containing a letter or a 
set of overhead slides normally contains all the tags for the complete 
document. An individual file can contain several chapters, and when 
processed, the chapters are automatically numbered in the order that 
you place them in the file. Processing individual files is discussed in 
Section 4.3. 


e As a book (processed in a bookbuild) 


You have a set of SDML files, each of which contains a portion of a 
book. To do a bookbuild, you must put the text and SDML tags for each 
individual chapter in a unique file. You then create a file called a profile 
that lists the files that contain the individual chapters. Bookbuilding is 
discussed in Section 4.5. 


e As an element of a book (processed in a book element build) 


An element is a single file that is a part of a book; for example, the tags 
and text for a single chapter. When you have made extensive changes to 
an element of a book, or when a colleague requests a copy of a particular 
chapter, you can use an element build to process and print the single 
chapter only. Book element processing is discussed in Section 4.6. 


e Asa subelement of a book (processed in a book subelement build) 


A book element can be divided into smaller parts, with each part kept 
in its own file. Each is considered a subelement of the book, and can be 
processed individually. Subelement processing is discussed in Section 4.7. 
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Processing a file that is an element or subelement of a book is useful if you 
need only part of a book for review purposes or if you want to make sure that 
your references to other parts of the book are correct after you make changes 
to the input file. You do not have to process the entire book to resolve the 
references correctly. (Using cross-references is discussed in Chapter 6.) 





4.2 Chain of Processing 


The chain of processing begins when you invoke VAX DOCUMENT from the 
command line. Each processor creates an intermediate file and passes that file 
on to the next processor. The input file is processed in the following order: 


1 The tag translator creates a .TEX file. 
2 The text formatter creates a .DVI_—device file. 


3 The device converter creates an output specific file, with the file type of 
LNO3, LINE, PS, TERM, or TXT. This final file is sent to the output device 
for printing or reading through the VMS Mail Utility or on the terminal 
screen. 


No matter the type of build, the input file you specify on the command line is 
processed in the order of the tag translator, the text formatter, and the device 
converter, and then sent to a print queue. You can specify that one or more 
processors be skipped during the processing of a file. The reasons for doing 
this and the qualifiers used are discussed in the following sections. 





4.3 Processing Individual Files 


A single generically coded input file can be processed and printed on a 
hardcopy device, viewed on a terminal screen, or viewed from within 
electronic mail. 


After creating an input file, you process it by typing the DOCUMENT 
command line using the following syntax: 


$ DOCUMENT input-file-spec doctype.design destination 
The command line parameters must be specified in the order shown. 


On the command line, the input-file-spec is the name of the input file you 
want to process. Usually, you do not have to specify the file type of the input 
files VAX DOCUMENT assumes the correct file type. 


The doctype for your file is the second parameter on the command line. The 
doctype you choose depends on the type of information you are documenting 
and on the document design you prefer. Certain doctypes contain tags 
specific to certain types of information. For more information on these 
doctype-specific tags, see VAX DOCUMENT User Manual, Volume 2. If you 
are not sure which doctype to use, you can look through VAX DOCUMENT 
Design Samples to choose an appropriate design. 


Specify the destination to which you intend to send the output as the third 
parameter. When processing an individual file, you can specify any of five 
destinations on the command line: three supported types of printers, a 
terminal, and an electronic mail destination. The keywords you use to specify 
these destinations are shown in Table 4-1. 
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Note: 
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Your system manager may set up site-specific destination keywords for your 
installation. Destination keywords can be abbreviated. 


Table 4—1 Destination Keywords 


Keyword Destination 

LINE Any line printer supported at your site. Produces a file 
that uses overstriking to achieve bold and underlined 
text. 

LNO3 The DIGITAL LNO3 or LNO3 PLUS laser printers. 

MAIL The VMS Mail Utility. Produces a file that does not 
display bold or underlined characters. 

PS Any supported POSTSCRIPT device. 

TERMINAL Any ANSI terminal, such as the VT100, VT200 or 


VT300 series. Produces a file that uses ANSI control 
sequences to achieve bold and underlined text. 


The command line accepts qualifiers to control aspects of the processing. 
Those qualifiers are discussed in this chapter; the entire set of qualifiers is 
explained in Appendix A. 


After being processed, the file is printed automatically (except when using the 
terminal or mail destinations) unless you specify the /NOPRINT qualifier on 
the command line. 


When processing interactively, it is good practice to use the /LIST 
qualifier on the DOCUMENT command line to capture any error 
messages. The LIS file that is created to hold the messages is placed 
in your current directory and named input-file-spec.LIS. To use this 
qualifier on the command line, type the following command line: 


$ DOCUMENT input-file-spec doctype destination /LIST 





Controlling File Processing 


So far, this chapter has mentioned several qualifiers that, when added to 
the command line, allow you to process book elements, include other input 
files into the final output, or map the files processed during a bookbuild. 
DOCUMENT command line qualifiers also can be used to control how 
processing occurs, which processors will be used, and what portion of a 
document gets processed. 


Each qualifier should be specified on the command line only once. If a 
qualifier is specified more than once, only the last use of that qualifier takes 
effect. The following qualifiers are discussed in this section: 
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/BATCH 
/CONDITION 


/DEVICE_CONVERTER=(HORIZONT AL _OFFSET=points) 
/DEVICE_CONVERTER=(VERTICAL _OFFSET=points) 


/DEVICE_CONVERTER=(STARTING_PAGE=folio) 
/DEVICE__CONVERTER=(ENDING_PAGE=folio) 
/DEVICE_CONVERTER=(NUMBER_OF_PAGES=total-pages) 
/INCLUDE 

/KEEP 

/NODEVICE_CONVERTER 

/NOTAG_TRANSLATOR 


/NOTEXT_FORMATTER 


/OUTPUT 
/SYMBOLS 


Causes the process to be done in batch 
mode. 


Sets a condition for the file being 
processed. 


Each of these qualifiers alters the default 
position of the text page for the whole 
document. 


Each of these qualifiers processes and 
prints only those pages selected. 


Includes an additional SDML file before the 
input-file. 


Specifies that the intermediate files should 
be kept in the current directory. 


Processes a file without running it through 
the device converter. 


Processes a file without running it through 
the tag translator. 


Processes a file without running it through 
the text formatter. "3 


Specifies a new name for the output file. 


Includes a file containing symbol name 
definitions for symbols that are referenced 
in a source file. 


Keeping Intermediate Files (Using /KEEP) 


By default, the intermediate files are automatically deleted from your directory 
after they are used in the processing chain. You can keep the intermediate 
files for later use by specifying the /KEEP qualifier on the command line. 


If you keep the intermediate files, you can reprocess a document from any 
stage of the processing chain. By specifying the appropriate combination of 
command line qualifiers, processing starts at the specified point: 


¢ To start the processing chain after tag translation, specify /NOTAG— 
TRANSLATOR on the VAX DOCUMENT command line. You must have 


a TEX file to start at this point. 


e To start the processing chain after text formatting, specify /NOTAG— 
TRANSLATOR and /NOTEXT_FORMATTER on the VAX DOCUMENT 
command line to suppress the tag translator and the text formatter. You 
must have a DVI_device file to start at this point. 


e To print the output file without reprocessing it, specify /NOTAG— 
TRANSLATOR, /NOTEXT_FORMATTER, and /NODEVICE— 
CONVERTER to suppress the tag translator, the text formatter, and 
the device converter. You must have a device-specific output file, such as 


a FILENAME.LNO3 file. 
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4.4.2 Processing in Batch Mode (Using /BATCH) 


You can specify a qualifier on the command line that submits your 
DOCUMENT command for processing as a batch job, instead of running it 
interactively (interactive processing occurs by default). By specifying /BATCH 
with the rest of your command line, you can continue processing while your 
terminal is free for other use. Also, by default, the /BATCH qualifier creates a 
log file, with the same file name as the input file and a file type of .LOG. The 
log file, which is placed in your current directory, contains a listing of any 
processing errors found by the tag translator or by the text formatter. The log 
file can be typed or edited. 


When processing in batch, there is no need to use the /LIST qualifier if the 
batch log file is printed or kept. 


The /BATCH qualifier accepts many keywords to modify the batch processing 
activity. These keywords are the same as the DIGITAL Command Language 
(DCL) SUBMIT command qualifiers, which are explained in the VAX/VMS 
DCL Dictionary. An example is shown in Appendix A of this manual. 


4.4.3 Printing an Existing File 


Ordinarily, a file is printed automatically when you issue the DOCUMENT 
command, unless you specify the /NOPRINT qualifier or the destination as 
TERMINAL or MAIL on the command line. However, you might want to 
print a file that has been previously processed and printed or one for which 
you previously suppressed printing. In this case, specify that the file does 
not require tag translation, text formatting, or device conversion, by using the 
following qualifiers on the command line: 


$ DOCUMENT file-spec doctype destination /NOTAG_TRANSLATOR - 
$_/NOTEXT_FORMATTER /NODEVICE_CONVERTER 


Print only those files that were successfully processed through the device 
converter. Use the DOCUMENT command line, specifying the command 
line qualifiers /NOTAG_TRANSLATOR, [NORE RTTER: and 
/NODEVICE_CONVERTER. 


You can use the DCL PRINT command to print files if you want to get a hard 
copy of your input file, including the untranslated code, or if you want a hard 
copy of the LOG or LIS file. You can also use the DCL PRINT command to 
print, with the appropriate qualifiers, any of your final output files, as shown 
in Table 4-2. The queue names are defined by your system manager. 


Table 4—2 DCL Commands for Printing Files 


Type of Output File DCL Command 
LINE, TXT, or TERM $ PRINT filename /QUEUE=queue-name 


LNO3 $ PRINT filename /QUEUE=queue-name /NOFEED 
/PASSALL 
PS $ PRINT filename /QUEUE=queue-name 


/PARAMETER=(DATA_TYPE=POSTSCRIPT) 
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4.4.4 Reprocessing a File for a Different Destination 


Note: 


You cannot reprocess a DVI_device file to make the file readable by a 
device other than the one for which the file was originally processed. 
The exceptions to this rule are files processed for the LINE, TERMINAL, 
and MAIL destinations. These destinations all use the same DVI_LINE 
intermediate file, so you can reprocess for these different destinations. 
Files processed for LN03 or PS destinations should be sent to a different 
destination by specifying the following command line: 


$ DOCUMENT file-spec doctype destination 


Or you can reprocess a TEX file (if the TEX file was kept) by skipping the tag 
translation stage: 


$ DOCUMENT file-spec.TEX doctype destination /NOTAG_TRANSLATOR 


The TEX file has already been processed through tag translation, so the 
/NOTAG_TRANSLATOR qualifier specifies that the file should not be 
processed through the tag translator again. 


You cannot reprocess a TEX file using a different doctype than the one 
specified on the original command line. This could cause errors and the 
results are unpredictable. 


4.4.5 Processing or Reprocessing Selected Pages (Using 
/DEVICE_CONVERTER) 


Note: 


If you want to process and print (or reprocess and print) selected pages of 
a document, you must have kept the DVI_device file. To process selected 
pages, use the /DEVICE_CONVERTER command line qualifier with the 
following keywords: 


e /DEVICE_CONVERTER=STARTING_PAGES=5, which instructs the 
printer to begin printing with page 5 of the document. 


¢ /DEVICE_CONVERTER=ENDING_PAGE=3, which instructs the printer 
to print pages 1, 2, and 3. 


e /DEVICE_CONVERTER=(START=5, NUMBER=3), which instructs the 
printer to print pages 5, 6, and 7. 


Alternately, you can use the following qualifier: 


e /DEVICE_CONVERTER=(NUMBER—OF_PAGES=total-pages) which 
specifies the number of pages to print, when no ENDING_PAGE 
keyword is specified. 


When you specify more than one keyword to the /DEVICE_ 
CONVERTER qualifier, enclose the keywords in parentheses and separate 
them by a comma. 


The ENDING_PAGE and NUMBER—OF_PAGES keywords cannot be 
used together on the same command line. If they are used together VAX 
DOCUMENT will issue an error message. 


Refer to Appendix A for more information on these /DEVICE_CONVERTER 
qualifier keywords. 
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4.4.6 Altering Page Parameters (Using /DEVICE_CONVERTER) 


The /DEVICE..CONVERTER=(device-keyword) qualifier contains a useful 
feature for altering the page positioning of an entire document. The following 
qualifiers shift the printed image on the page: 


e /DEVICE_CONVERTER=(HORIZONTAL —OFFSET= number-of-points) 
is used to specify the text positioning of a document’s left margin. The 
HORIZONTAL — OFFSET keyword shifts the image horizontally. 


e /DEVICE_CONVERTER=(VERTICAL _OFFSET=number-of-points) is 
used to specify the text positioning of a document’s top margin. The 
VERTICAL—OFFSET keyword shifts the image vertically. 


In both cases, the number of points is an integer that specifies how far from 
the margin the text should be shifted (72 points is equal to 1 inch). The 
default horizontal and vertical offsets are both set to 72 points. 


4.4.7 Including Additional Files (Using /INCLUDE) 


To include an additional file in your final output, specify the /INCLUDE 
qualifier on the DOCUMENT command line. 


The /INCLUDE qualifier specifies that a file is included at the front of 
your output. It assumes a file type of SDML for the included file if none is 
specified, but accepts other file types. 


An example of a file that might be included with the /INCLUDE qualifier is 
a cover page that reads “For Internal Use Only.” The input file that contains 
the cover page text, perhaps called COVERPAGE.SDML, would be specified 
on the command line with /INCLUDE=coverpage. 


Another way to include a file is to use the <INCLUDE> (file-spec) tag. This tag 
serves the same purpose as /INCLUDE, except that the file is included into 
your output file at the exact location of the tag. 


4.4.8 Conditionalizing Files (Using /CONDITION) 


VAX DOCUMENT allows you to conditionalize an input file so that you can 
process the same file to obtain different output for different purposes. The 
/CONDITION qualifier can be used on the DOCUMENT command line to 
establish the condition under which the file is processed. 


For an example of a conditionalized file, consider the following situation: you 
want to write two letters, one to a friend and one to an acquaintance. You 
want most of the text of the two letters to be the same, but you want to add 
a personal note only to your friend. In this case, you actually need to write 
only one letter. 


If the file that contains the letter is called MYLETTER, you can create 
conditional sections in MYLETTER, with <CONDITION> (personal) tags, where 
“personal” is the condition-name. Then, you process this file twice. You 
process the letter to the acquaintance, using the usual DOCUMENT command 
line. You also process the letter to your friend, but this time, you use the 
/CONDITION qualifier on the command line, specifying the condition as 
“personal.” For example: 


$ DOCUMENT myletter LETTER LNO3 /CONDITION=personal 
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4.4.8.1 


4.4.8.2 


When the same condition-name used in the <CONDITION> tag is specified 
on the command line, all text that was tagged with that condition-name 

is included in the output. In this example, all of the text tagged with 
<CONDITION> (Personal) is included. The same text is suppressed when 
the /CONDITION qualifier is not specified on the command line. 


If you have placed <CONDITION> tags in your file, but do not set the 
condition during processing, no error message is generated. In this case, the 
conditionalized text is suppressed. 


Using the <SET_CONDITION> Tag 

You can set a condition by using the <SET_CONDITION> tag. Then, you do 
not use the /CONDITION qualifier when you process the file, but instead set 
the condition in the file, itself, at the top of the file. 


Continuing with the same example, you could place the tag 
<SET_CONDITION> (personal) in a separate SDML file (called FRIEND_ 
NOTES.SDML) and include that file at the beginning of your input 

file, MYLETTER.SDML, by using /INCLUDE=FRIEND_NOTES. In 
FRIEND_NOTES, you could also define symbols to be used only when 
Condition=personal is set. You can even include text in that file, so that the 
text is included only when the condition is set. 


There is no distinction between a condition that is set with a /CONDITION 
qualifier on the command line and a condition that is set by a 
<SET_CONDITION> tag in an input file. 


If you set the same condition on both the command line and in the file, no 
error will result. 


Setting More than One Condition 

It is possible to use more than one condition name to create conditional 
sections of an input file. You can tag some text elements with one condition 
name, and other text elements with a different condition name. During 
processing, the conditional text that does not match a set condition is not 
included in the output. 


To set more than one condition in a file, you must use <SET_CONDITION> 
tags on all but one condition, because the /CONDITION qualifier can set 
only one condition. 


For information on using conditions during bookbuilding or related 
processing, see Section 4.6.1. 


4.4.9 Assigning a New Output File Name 


If you choose to process a conditional file twice to get two different output 
files, you may want to use a DOCUMENT command line qualifier that 
assigns a name to the output other than the one assigned by default. 
/OUTPUT=file-spec gives the final output file any name that you choose. 


Continuing with the previous example, the letter to your friend can be 
processed and the output given a name that clearly identifies it, if you used 
the following command line: 


$ DOCUMENT myletter LETTER LNO3 /CONDITION=personal /OUTPUT=friend_letter 


4.5 


4.5.1 


Bookbuilding 
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Besides processing an individual file, you can process a group of files as a 
book. This process is called a bookbuild. The major benefit to processing 
a file as part of a book is that the bookbuild creates a file that contains 
all the symbol names that you have used throughout the book. You can 
subsequently reprocess individual elements of the book using the file of 
symbol names to resolve cross-references to other elements of the book. 


There are three steps to processing a group of input files through a bookbuild: 


1. Create the book element input files, naming them with SDML file types. 
These files can be empty but each file must contain a book element tag, 
and these must have symbol-names. Book elements are discussed in 
Section 4.5.1. 


2 Create a profile, naming this file with an SDML extension also. A profile 
contains a list of <ELEMENT> tags that specify the elements that compose 
your book. Once created, this profile becomes the file that you specify on 
the DOCUMENT command line for processing. 


3 Process the profile. 


Each step in building a book is described in the following sections. 


Creating Input Files 


When the structure of the book is clearly known, create a file for each 
element. All of the text need not be written. Use a <CHAPTER> or 
<APPENDIX> tag to head each element, and add <HEADx> tags if you 
have an outline of the chapter. The actual paragraphs of text can be filled in 
when you come to write the chapter. 


If you have not yet decided on the order of the chapters, or if the order could 
change, name each chapter with a descriptive name (for example, INTRO 
CHAP.SDML) instead of a numbered title (as in CHAP1.SDML). You can 
then easily reorder the chapters without renaming the files that contain them. 


When creating your book element input files, remember the following points: 


e Place each book element in a separate file by placing one of the following 
book element tags in the file as its first tag: 


<APPENDIX> 
<CHAPTER> 
<FRONT_MATTER> 
<GLOSSARY> 
<PART> 


e A book element file should contain only one of the book element tags. 
For example, two <CHAPTER> tags should not be placed in one file if 
you want to process that file in a bookbuild. The tag that identifies the 
file as a book element must be the first tag to appear in the file. 


e Each book element tag must contain a symbol-name argument if it will 
be part of a bookbuild. 


e There must be one file for each book element. 
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4.5.2 Creating a Profile 
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A profile is an SDML file that contains a list of all of the elements in a book, 
including the front matter, chapters, appendixes and glossary, if any. The 
profile also can contain tags that specify where a table of contents or index 
should be placed in the book and tags that specify logical names for files that 
are included. Only a specific set of tags can be placed in the profile. All valid 
profile tags are listed in Table 4-3. 


Table 4-3 Profile Tags 





Tag Purpose 

<PROFILE> Signals VAX DOCUMENT that the file is a profile 
submitted for a bookbuild. 

<ELEMENT > (file-spec) Identifies the file specification of an element of the 
book. 

<INCLUDES_FILE> (logical- Defines a logical name for the file specification of a 

name\file-spec) file included within the previous book element. See 
Section 4.5.3.2. 

<CONTENTS_FILE> t Specifies the location in the book where a table of 
contents file should be included. 

<INDEX_FILE> f¢ Specifies the location in the book where an index 
file should be included. 

<COMMENT> t+ Used to make comments about the elements of 
the profile. 

<ENDPROFILE> Terminates the profile. 


+These tags are also valid in files other than profiles. 


To create a profile that reflects the structure of the book, list (in a separate 
input file) all the files that are part of the book, tagging each file name in the 
list with an <ELEMENT> tag. In the front of the file, place the <PROFILE> 
tag, and at the end of the file, place the <ENDPROFILE> tag. Give this SDML 
file a unique name that indicates it is a profile (for example, MYBOOK_— 
PRO.SDML); processing a profile file that is named the same as one of your 
other SDML files can cause a fatal processing error. 


Each <ELEMENT> tag should specify a file that contains a book element. An 
example of a profile for a book named How to Use a Computer follows: 


<PROF ILE> <COMMENT> (+**Profile for How to Use a Computer***) 


<CONTENTS_FILE> <COMMENT>(***insert table of contents here***) 
<ELEMENT> (Mydisk: [Mydirectory] intro_chap.sdml) 
<ELEMENT>(Mydisk: [Mydirectory] applications_chap.sdm1) 
<ELEMENT> (Mydisk: [Mydirectory]tools_chap.sdm1l) 

<ELEMENT> (Mydisk: [Mydirectory]conclusion_chap.sdml) 

<ELEMENT> (Mydisk: [Mydirectory]questions_app.sdm1l) 


<INDEX_FILE> <COMMENT>(***insert index here***) 
<ENDPROF ILE> 


Each of the book element files listed in the example must contain a book 
element tag and a symbol name for that element. For example, the chapter 
TOOLS_CHAP.SDML should begin with the following tag: 


<CHAPTER>(Using Basic Computer Tools\comp_tools_chap) 
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“Using Basic Computer Tools” is the chapter title and “comp_—tools_chap” is 
the symbol name of the chapter. 


4.5.3 Processing a Profile 


4.5.3.1 


4.5.3.2 


To perform a bookbuild, use the following command on the command line: 
$ DOCUMENT profile-spec doctype destination 


Profile-spec specifies the name of the SDML file containing the profile of the 
book being processed. 


VAX DOCUMENT recognizes that it is building a book when it reads the 
<PROFILE> tag in the profile. Processing the profile creates a cross-reference 
(XREF) file for the book. For example, if MYBOOK—PRO.SDML is the profile 
name, typing the following line creates a complete cross-reference file of all 
the symbol-names in the book. The cross-reference file is called MYBOOK— 
PRO.XREF and the final output file (processed for the REPORT doctype) is 
called MYBOOK_PRO.LNO3. 


$ DOCUMENT MYBOOK_PRO REPORT LNO3 /CONTENTS /INDEX 


You might want to process a profile with the /NOPRINT qualifier so that the 
book is not printed by default. You must specify /CONTENTS and /INDEX 
if you want table of contents and index files. 


Listing the Input Files 

A command line qualifier that is useful during a bookbuild is /MAP. This 
qualifier lists all the input files processed by VAX DOCUMENT in one 
separate MAP_LIS file, thereby keeping track of the files included and their 
order. The list starts with the first input file processed and includes any input 
files specified by <ELEMENT> or <INCLUDE> tags. In the list, files that are 
included by other files are indented under those files. 


If you do not specify a file type, the MAP file is given the same name as the 
profile with a file type of MAP_LIS. 


The /MAP qualifier is valid only if tag translation is being done. If 
/NOTAG_TRANSLATOR is specified with the /MAP qualifier, the /MAP 
qualifier is ignored, and VAX DOCUMENT issues an informational message 
stating that you have specified conflicting qualifiers. 


Defining Logical Names for Included Files 

To define logical names for included files in book elements, use the 
<INCLUDES_FILE> tag in your profile. The <INCLUDES_FILE> equates a 
logical name with a file specification during VAX DOCUMENT execution. 
The tag’s format follows: 


<INCLUDES_FILE>(logical-name\file-spec) 


Place the <INCLUDES_FILE> tag in your profile to define a logical name for 

a file whose contents are included in one of your element files. The first 
argument to <INCLUDES_FILE> is the logical name for the included file. You 
then use this name as the argument to the <INCLUDE> tag in one of the book 
element input files. The second argument specifies the actual file specification 
into which the logical name translates. 
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The <INCLUDES_FILE> tag is valid only within a profile. You should place 

it directly after the <ELEMENT> tag that names the book element file that 
includes the input file. During a bookbuild, VAX DOCUMENT establishes the 
logical name definition for each <INCLUDES_FILE> tag before it actually reads 
and processes the element file name in the preceding <ELEMENT> tag. The 
logical name remains defined during the processing of later elements. 


When an element or subelement is processed by itself (when you use 
the /PROFILE qualifier on the command line), VAX DOCUMENT 
again establishes the logical name definitions that were specified by the 
<INCLUDES_FILE> tags in the profile. 


The following example illustrates the use of the <INCLUDES_FILE> tag ina 
profile: 


‘A writer is drafting a book titled Purebred Dogs. The book contains two 
chapters, one discussing different breeds, and one on the care of purebreds, 
In addition, there is front matter (title page and preface) and an appendix. 


The file identified in each <ELEMENT> tag corresponds to the exact file-name 
of each book element file. The profile, named CANINE—PRO.SDML, looks 
like this: 


<PROFILE> 
<ELEMENT> (FRONT . SDML) 
<ELEMENT> (BREEDS . SDML) 
<ELEMENT> (CARE. SDML) 
<ELEMENT> (APPENDIX . SDML) 
<ENDPROFILE> 


If the book element “CARE.SDML’” itself includes two figures and each figure 
is in a separate SDML file, those figure files could be included by logical- 
names instead of full file specifications. The logical-names could be defined 
right in the profile, as follows: 


<PROFILE> 
<ELEMENT> (FRONT . SDML) 
<ELEMENT> (BREEDS . SDML) 
<ELEMENT> (CARE . SDML) 
<INCLUDES_FILE>(bassets_fig\mydevice: [mydirectory]dogcare_figi.sdml) 
<INCLUDES_FILE>(beagles_fig\mydevice: [mydirectory]dogcare_fig2.sdm1) 
<ELEMENT> (APPENDIX . SDML) 
<ENDPROF ILE> 


In CARE.SDML, you might have the figures referenced and included as 
follows: 


<P>The following illustration shows all the basset hound breeds of North 
America. 
<INCLUDE> (bassets_fig) 


<P>In comparison, the next figure illustrates the beagle types throughout 
North and South America. 
<INCLUDE> (beagles_fig) 


Notice that the <INCLUDES_FILE> tag in the profile does not actually include 
the figure, but assigns a logical name to the figure file. Refer to the tag 
description in Chapter 9 for an explanation of the tag’s syntax. 


| 
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4.5.4 Recovering from Errors 


If any of your book element input files contain enough tag translator errors 
to halt the processor, the tag translator will not produce a .TEX file of 
that element, and the bookbuild will stop after the last element has been 
processed. To fix this, you should take the following steps: 


1 Fix the errors in the book element input files. 


2  Reprocess each revised book element file by typing the following 
command: 


$ DOCUMENT input-file-spec doctype destination /NOTEXT_FORMATTER 
/PROF ILE=profile-spec 


The input-file-spec is the specification of that individual book element file 
and the profile-spec is the specification of the profile. 


3 Submit the bookbuild again, this time using the /NOTAG_— 
TRANSLATOR qualifier to avoid sending the entire book through the 
tag translator for a second time: 


$ DOCUMENT profile-spec doctype destination /NOTAG_TRANSLATOR 


Chapter 5 discusses troubleshooting of errors in more detail. 





4.6 Processing an Element of a Book 


As mentioned in Section 4.1, you can process a book element individually 
by treating it as a stand-alone file and specifying the file name on the 
DOCUMENT command line. However, any references to symbol names 
outside of that element will not be resolved. 


To process an individual book element and have all its references resolved 
correctly, you must have previously processed the entire book through a 
bookbuild to create an XREF file. Then, to process only one element, you 
can specify the name of the XREF file to the command line, telling VAX 
DOCUMENT where to find the symbol-names to resolve the references in the 
element. The name of the XREF file is specified on the command line with 
the /PROFILE qualifier. 


The XREF file has the same name as your profile, but has the file type of 
XREF, 


To process a book element individually, use the following command on the 
command line: 


$ DOCUMENT input-file-spec doctype destination /PROFILE=profile-spec 


Input-file-spec specifies the input file to be processed. Profile-spec identifies 
the name of the cross-reference file that contains the symbol names of the 
book. 


This command line processes an element of a book and sends it to the 
specified destination. All symbol-name references within the element are 
resolved; however, the page numbering begins with 1. 


Notice that the /PROFILE qualifier is used only to identify the XREF file 
during an element or subelement build. You should not use the /PROFILE 
qualifier when doing a bookbuild because you specify the profile name as the 
file to be processed. 
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For more information about referencing symbol names, see Chapter 6. 


4.6.1 Building a Conditionalized Book Element 


When you build a book element after building the whole book with a 
condition set, the condition is automatically set in the element build. This 
happens because the /CONDITION qualifier is stored in the cross-reference 
file during the bookbuild and then re-used. 


If you want to build an element of a conditional book without the condition, 
you need to specifically override the condition during the element build. 

At the time of the element build, use the /CONDITION qualifier on the 
command line, specifying a new condition name. The new condition name 
supplants the original condition for that element. The new condition name 
can be any fictitious name (for example, /CONDITION=FAKE). Since you 
have no <CONDITION> (fake) tags in your book element input file, no text will 
be eliminated from the output file. 





4.7 Processing a Subelement of a Book 
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Note: 


If a book element is long enough to be divided into more than one file, 
creating subelement files, you can process any of those subelements 
individually. To do this, use the following command on the command 
line: 


$ DOCUMENT input-file-spec doctype destination - 
_$ /ELEMENT=file-spec /PROFILE=profile-spec 


input-file-spec specifies the subelement input file to be processed. 


/ELEMENT=file-spec identifies one of the files listed in the profile; the file 
specified in the input-file-spec is a subelement of this element. 


/PROFILE=profile-spec identifies the XREF file containing the book’s symbol 
names. 


This command line processes a subelement of a book and sends it to the 
specified destination. Cross-references within the subelement are resolved 
and a new XREF file is created; however, the page numbering begins with 1. 


For a subelement build, the book element file and all the other 
subelement files need to be present, because the tag translator reads the 
whole element and all its included files even though the entire element is 
not included in the output. 


You only need to do a subelement build if one of the following conditions 
exists: 


e The file is included in another file that is listed as an <ELEMENT> ina 
profile. 


e The file contains references to symbols defined in other files. 


e You want the output file to have the same heading level numbers, table 
and figure numbers, and so on, as if the file were processed with the 
entire element. 


Heading level numbers, figure numbers, and table numbers, are correct only 
if they have symbol-name arguments. 
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You do not need to use a subelement build if you are only processing a file 
to check text content or spelling. in this case, you can process the subelement 
file as a stand-alone file. 





4.8 Simultaneous Element Builds and Bookbuilds 


If two or more users are working on the same book and try to process 
separate elements of the book simultaneously, specifying the /PROFILE 
qualifier to reference the XREF file for the book, the XREF file may not be 
accessible by one of the users and cross-references will not be resolved. 


For example, one user opens the XREF file and loads it into memory 

prior to doing the build on a book element. The tag translator locks the 
existing XREF file, so that no one else can use it until a new XREF has been 
successfully written. The file is locked to ensure that any symbol name 
changes introduced by an element build will get incorporated in subsequent 
builds. 


VAX DOCUMENT protects against the use of an old XREF file by locking the 
file. A second user will be unable to open the XREF file. That user receives 
an error message about the XREF file failing to open, and the tag translator 
halts. 


Writers can work independently on separate chapters of a book and can do 
their element builds without concern for the actions of other writers. But 
they should be prepared for an error message from the tag translator if they 
attempt to do an element build at the precise moment that another writer has 
the XREF file locked. 


If you get such a message, wait a minute or two and try the element build 
again. The lock happens only during the first pass of the tag translator, when 
it is reconstructing the XREF file, so even though it may take several minutes 
to completely process a chapter, the actual time that the XREF is locked will 
be less. 


Likewise, when someone starts a bookbuild, and the <PROFILE> tag is 
encountered, any existing XREF file is locked. Therefore, other users cannot 
be doing element builds using this XREF file. If the writer doing an element 
build opens the XREF file right before a bookbuild begins, the bookbuild itself 
will abort. 


A writer doing a bookbuild should coordinate with other writers working on 
the book. The locking action acts as a safeguard against a book or element 
build using an old XREF file for resolving cross-references. 
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Fs Troubleshooting SDML Files 


During processing, VAX DOCUMENT diagnoses the source file and checks 
for errors. Error messages are produced when VAX DOCUMENT encounters 
the following error conditions: 


e Misspelled SDML tags and argument names 
e¢ Tags used out of proper context 
e Missing terminating tags 


VAX DOCUMENT issues a message that provides the line number, the 
probable cause, and other information about the error. The user returns to 
the source file to correct the error and reprocess the file. 


However, in some cases, the file processes without producing any error 
messages, but the printed output clearly indicates that something has been 
forgotten or that something needs to be adjusted. A few problems of this 
nature are quite common and examples of incorrect and correct input are 
shown in this chapter. 


If you have a batch process running for an abnormally long amount of time, 
have your system manager check that the system parameters are set correctly, 
including the required space quota amount. 





5.1 Error Messages 


Error messages and informational messages are produced by each of the 
processing programs in the VAX DOCUMENT system: 


e The tag translator 
e §©The text formatter 


e The device converter 


VAX DOCUMENT messages have the following general format, consisting of 
four fields: 


%FACILITY-S-IDENT, text... 

Facility 

The facility field in the message identifies the program that issues the 
message. 


The following are VAX DOCUMENT facility prefixes: 
¢ %DOC 
¢ %TAG 
¢ %DVC 
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Severity 


The severity field indicates the seriousness of the error. 
e I—The message is informational; processing is not affected. 


¢ W—tThe message provides a warning; processing is not terminated. 
A warning is produced if arguments are supplied where they are not 
necessary, or if a tag has been misspelled, such as <TABLER> . 


If the tag translator generates more than 30 warnings by the time it 
finishes its first pass through a file, it stops processing at the end of 
that pass. You can see the error messages and fix the errors before 
reprocessing the file. 


e¢ E—A major error has occurred; processing continues, but no output may 
be produced. 


¢ F—The message indicates a fatal problem; processing is terminated. 


Fatal problems, such as missing terminator tags, must be corrected before 
the file can be processed further. 


Identification 


The identification field is an abbreviation of the problem found by the 
processing program. 


Text 


The text of the message, if present, describes the problem found by the 
processing program. The following error message is an example of the 
message format: 


4, TAG-W-GTMAXARGS at tag <P> on line 1 in file 
disk: [directory]filename.SDML 
More than O arguments supplied to tag <P> 


%TAG-W-GTMAXARGS 


The facility, severity, and identification of the message. This warning message 
was issued by the tag translator. 


at tag <P> online 1 in file 


The first line of text provides the line number and the name of the tag being 
evaluated when the message was issued. 


disk:[directory]filename.SDML 
The second line of text provides the name of the file being read. 


More than O arguments supplied to tag <P> 
The third line identifies the problem. 


If VAX DOCUMENT is running interactively, error messages from the tag 
translator are displayed on the screen and recorded in a LIS file if the /LIST 
qualifier is used. The LIS file has the same name as the source file, with the 
LIS file extension. Error messages from the text formatter are written to a LIS 
file. 


If VAX DOCUMENT is running in batch mode, error messages are 
automatically written to a LOG file. 
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5.2 Output Problems 


Sometimes processing completes without an error, but when the output is 
printed, it is easy to see that things have somehow gone awry. 


This section illustrates some common solutions to problems that a writer must 
diagnose after seeing the formatted output. 


5.2.1 Incorrect Paragraph Spacing 


A common mistake when coding a file is to leave out <P> tags. Most often, 
the tags are left out after major headings, such as chapter titles and headings. 


The problem is only apparent in doctypes that place headings at a different 
margin than paragraphs. 


Incorrect Input 


<CHAPTER>(symbol-name) 
Paragraph text... 


<HEAD1>(First-level Heading) 
The information in this chapter covers... 


<P>Also including is... 


<HEAD2>(Second-level Heading) 
First item under discussion. 


<P>Details... 


Correct Input 

<CHAPTER>(symbol-name) 

<P>Paragraph text... 

<HEAD1>(First-level Heading) 

<P>The information in this chapter covers... 
<P>Also including is... 

<HEAD2>(Second-level Heading) 

<P>First item under discussion. 


<P>Details... 


5.2.2 Problems with Examples 


Code examples, interactive examples, and syntax examples appear on the 
printed page as monospaced output. Because of the change to a monospaced. 
font, examples restrict the use of many tags. Tags that require special 

text formatting, such as lists, tables, and headings, cannot be used within 
monospaced examples, nor may index tags be used. 


When the <CODE_EXAMPLE> tag is used with the <ENDCODE_EXAMPLE> 
tag, spacing is preserved. However, when the <CODE_EXAMPLE> tag is used 
with an argument and no terminating tag, any leading or trailing spaces are 
not preserved. 
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Incorrect Input 


<TABLE> 
<TABLE_SETUP> (2\10) 
<TABLE_HEADS> (Variable\Value) 
<TABLE_ROW> (<CODE_EXAMPLE> (ABC) \<CODE_EXAMPLE>(. 1)) 
<TABLE_ROW> (<CODE_EXAMPLE> (XYZ) \<CODE_EXAMPLE> (100) ) 
<ENDTABLE> 


Correct Input 


In this example, the writer was trying to use the spaces to align the values in 
the table. The <ALIGN_CHAR> tag produces correct alignment: 


<ALIGN_CHAR> (#) 

<TABLE> 

<TABLE_SETUP>(2\10) 

<TABLE_HEADS> (Variable\Value) 
<TABLE_ROW>(<CODE_EXAMPLE> (ABC) \<CODE_EXAMPLE> (##1) ) 
<TABLE_ROW> (<CODE_EXAMPLE> (XYZ) \<CODE_EXAMPLE> (100) ) 

<ENDTABLE> 

<ENDALIGN_CHAR> 


5.2.3 Incorrect Sequencing of Formal Elements 
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Formal elements can be output out of sequence if coded inconsistently. 

For example, it is possible to code three figures that the tag translator 
automatically numbers 1, 2, and 3. In the output, the figures could possibly 
appear out of sequence, for example, as 2, 1 and 3. 


The problem arises if the figures are coded with the FLOAT attribute. After 
the tag translator numbers the figures, it is possible for the text formatter to 
float them out of order. 


Incorrect Input 


<FIGURE> (Caption\symbo11) 
<FIGURE_ATTRIBUTES> (FLOAT) 
<FIGURE_SPACE> (10) 
<ENDFIGURE> 


<FIGURE> (Caption \symbo12) 
<FIGURE_ATTRIBUTES> (FLOAT) 
<FIGURE_SPACE> (10) 

<ENDF IGURE> 


<FIGURE> (Caption\symbo13) 
<FIGURE_ATTRIBUTES> (FLOAT) 
<FIGURE_SPACE> (10) 

<ENDF IGURE> 


If all three figures are short, any of the figures could float out of order. To 
correct this problem, code all three figures with the KEEP attribute. 


Correct Input 


<FIGURE>(Caption\symbol11) 
<FIGURE_ATTRIBUTES> (KEEP) 


<FIGURE>(Caption\symbol2) 
<FIGURE_ATTRIBUTES> (KEEP) 


<FIGURE> (Caption\symbo13) 
<FIGURE_ATTRIBUTES> (KEEP) 
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6 Referencing Symbol-Names 


VAX DOCUMENT allows you to create and reference symbol-names for any 
type of information that is subject to change. This ensures that documents 
are always up to date, especially in regard to the following references: 


e References to text elements that might change, such as the name of a 
product or project. 


e References to book elements that have numbers associated with them, 
such as chapters. 


This chapter describes how to create symbol-names for text and book 
elements and how to reference them. 


A symbol-name is a term that you assign to some text which, once created, 
becomes an easy and reliable way to refer to past or future chapters, tables in 
other sections of the book, figures, other writers’ books, and numerous other 
references. 





6.1 Creating Symbol-Names 


You can create symbol-names for both text elements and book elements. 
Each symbol-name is assigned as a tag argument. For example, to assign a 
symbol-name to an example captioned VAXcluster Multi-file Summary, you 
could put the following tag into your SDML file: 


<EXAMPLE>(VAXcluster Multi-file Summary\multi_file_exam) 


The symbol-name multi_file_exam could then be referenced anywhere in the 
document, with the <REFERENCE> tag: 


<REFERENCE> (multi_file_exam) 


When VAX DOCUMENT processes the <REFERENCE> tag, it substitutes the 
actual name for the symbol-name in your output. In this case the symbol- 
name “multi_file_exam” would be replaced with “VAXcluster Multi-file 
Summary.” 


Symbol-names must not exceed 31 characters, and can consist only of 
alphabetic letters, numbers, and underscores. Do not begin a symbol-name 
with an underscore. 


The following naming convention might be useful: in each symbol-name, 
suffix the name with the type of text element for which you are creating a 
symbol. For example, a symbol-name for a table might be called “american 
kings_tab,” or for a chapter, “american_kings_chap.” This convention makes 
it easy to identify different types of symbol-names as you edit a source file. 
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6.2 Storing Symbol-Names in a Cross-Reference File 


An automatic function of VAX DOCUMENT is to create a cross-reference 
file, which is a file containing a list of the symbol-names used in one or 
more files. An entry in the cross-reference file may have some or all of the 
following information associated with it: 


e The symbol-name. As previously described, symbol-names must be no 
more than 31 characters in length, and must have only alphabetic letters, 
numbers, or underscores in them. 


¢ A -symbol-type. Each cross-reference file entry must have a symbol-type, 
~ which not only indicates the type of element to which a symbol refers 
(for example, Figure, Table, or Chapter), but may also control the output 
when the symbol is referenced. For example, if the element is a Chapter 
type, the output associated with the reference to it is the default text 
“Chapter.” 


e A symbol-value. Cross-reference file entries for text elements that have 
numeric values associated with them (header levels, figures, numbered 
tables, and so on) always associate this number with the symbol-value. 


e The symbol-text. The text associated with a cross-reference file entry is the 
text string associated with it: the chapter title, a figure caption, heading 
level text, or a user-defined string. 


When you process an individual file that contains symbol-names, those 
symbol-names are temporarily placed in the cross-reference file (in your 
computer system’s memory). VAX DOCUMENT uses the table to resolve all 
symbol-name references, then erases the table from memory. 


When you process a book through a bookbuild, or an element of a book 
through an element build, VAX DOCUMENT again creates a cross-reference 
file and uses it to resolve all references. However, the bookbuilding process 
requires that the symbol-names be stored for later use, so VAX DOCUMENT 
saves the cross-reference file by copying it into the directory that contains 
the profile used to perform the bookbuild. This copied file is named with the 
profile name and is given the filetype of XREF. 


Note: The XREF file is not readable; you should never attempt to edit it. Also, 
do not delete it; if it is deleted accidentally, you must perform a new 
bookbuild before any subsequent element builds can be done. 





6.3 Creating Symbol-Names for Text and Book Elements 


Text and book elements can be divided into two groups, sequenced and 
nonsequenced elements. 


A sequenced element is labeled in the output. The number or letter assigned 
is relative to the other elements of the same type in the rest of the book. For 
example, a table is assigned the number three only if there are two tables 
before it in the book element being processed. 
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The following tags mark sequenced elements and are used to create symbol- 
names for these elements: 


° <APPENDIX> 
: <CHAPTER> 
° <EXAMPLE> 
° <HEADx> 

7 <FIGURE> 

° <PART> 


° <TABLE> 


A nonsequenced element is any text string or book element that does not 
need to be numbered. An often used sentence or statement is an example of 
a nonsequenced text string. A book title is also a nonsequenced text element, 
as it does not receive a number. 


The following tags are used to create symbol-names for nonsequenced text 
elements: 


s <DEFINE_BOOK_NAME> 
bd <DEFINE_SYMBOL> 
° <FRONT_MATTER> 


bd <GLOSSARY> 


See Chapter 9 for full descriptions of these tags. 


The <DEFINE-SYMBOL> and <DEFINE_BOOK_NAME> tags accept a symbol- 
name as their first arguments. The book element tag <FRONT_MATTER> 
accepts a symbol-name as its only argument. For all other tags that accept 
symbol-names, assign the symbol-name as the tag’s second argument. 


Each book element requires a symbol-name if the book is to be processed 
through a bookbuild; if you use these tags without symbol-name arguments, 
no entry is added to the cross-reference file during processing and you receive 
a warning message. 


For example, a chapter might have its title and symbol-name identified as 
follows: 


<CHAPTER>(Running the Program\ref_chap) 


The <CHAPTER> tag creates a cross-reference file entry for this chapter. The 
chapter’s symbol-name is saved in the table as ref_chap. Other information 
associated with this symbol is also saved, including the chapter title, Running 
the Program, and the chapter number (which is assigned automatically). This 
chapter’s symbol-name, which appears in the <CHAPTER> tag argument 

at the head of the book element, becomes the key to element building, as 
described in Section 4.6 of Chapter 4. 
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6.4 Referencing Text and Book Element Symbol-Names 


The <REFERENCE> tag is used to reference any kind of symbol-name. 
The first argument to this tag is always the symbol-name you want to 
reference. Any symbol-name specified by the <REFERENCE> tag causes 
the tag translator to search the cross-reference file for the definition of the 
symbol-name and to replace the reference with the definition. For example: 


See <REFERENCE>(ref_chap) for step-by-step instructions. 


This book element reference causes the tag translator to look in the cross- 
reference file for the symbol-name ref_chap and to replace the tag and 
argument with the default symbol type keyword associated with the chapter 
(for example, “Chapter’) and the chapter number. Therefore, if the preceding 
example referenced the third chapter of a book, the output would be as 
follows: 


See Chapter 3 for step-by-step instructions. 


In your source file, the reference to a symbol-name can precede or follow the 
tag that defines the symbol-name. Therefore, the following line: 


<Define_Symbol>(plan_tab\The 43rd Project Plan) 
could be placed anywhere in the document, before or after the following line: 
<p>The series of steps are identified in <reference>(plan_tab) . 


Relative placement of the two tags is unimportant because the tag translator 
makes two passes over a document during processing, creating the cross- 
reference file during its first pass and not using the file to resolve the 
references until the second pass. Therefore, the correct symbol-names are 
always entered in the file before the references are translated. 


6.4.1 Controlling the Output of Your Reference 


The <REFERENCE> tag allows you to control the output of a reference 
through use of its second argument. You can use this argument to specify 
that you want either a portion of your reference or the entire reference placed 
in your output. 


Optional second arguments to <REFERENCE> include the following: 


e VALUE—specifies that, if a symbol-name has a value associated with 
it, you want only that symbol-value (number or letter) included in the 
output. 


e TEXT—specifies that you want only the text of a symbol included in the 
output (for example, a chapter title or table caption). 


e FULL—specifies that you want both the value and the text included in 
the output. 


Consider the earlier example of the <CHAPTER> tag. VAX DOCUMENT 
automatically assigns to the book element symbol-name its symbol-type 
keyword, “Chapter,” and its symbol-value, the sequential number of the 
chapter during processing. By default, both the symbol-type keyword and 
the symbol-value are used to replace the symbol-name reference. However, 
if you want the output to include the associated text of the symbol-name 
with the symbol-type keyword and value, you need to specify \FULL in the 
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reference. If “Running the Program” is the title of the fourth chapter, and you 
want that title to be included in your reference, you would use the \FULL 
argument. For example: 


<reference>(ref_chap\FULL) 
Such a reference would automatically output the following text: 
Chapter 4, Running the Program 


When you do not specify a second argument, the output defaults according to 
the symbol-type. Table 6-1 summarizes the default output for each type of 
text or book element. 


Table 6—1 Element Types and Default Output of Symbol-Names 


Text Element 
EXAMPLE 


FIGURE 


HEADx 


TABLE 


BOOK TITLE 
TEXT STRING 


Book Elements 
APPENDIX 
CHAPTER 

PART 

SECTION 

FRONT MATTER 
GLOSSARY 


Second Argument to <RrEFERENCE> 


(null) VALUE TEXT FULL 

“Example” number caption “Example” number, 

number caption 

“Figure” number number caption “Figure” number, 
caption 

“Section” number number caption “Section” number, 
caption 

“Table” number number caption “Table” number, 
caption 

The title argument specified in <DEFINE_BOOK_NAME> . 

The text-string argument specified in <DEFINE_SYMBOL> . 

(null) VALUE TEXT FULL 

“Appendix” letter —_ letter title “Appendix” letter, title 

“Chapter” number number title “Chapter” number, title 

“Part” number number title “Part” number, title 

“Section” number number title “Section” number, title 

none none none none 

none none none none 


Here is an example of a figure reference with a defaulted second argument: 


<P><reference>(keyboard_fig) shows the keypad layout. 


<FIGURE>(The Default Keys\keyboard_fig) 
<FIGURE_SPACE> (20) 


<ENDF IGURE> 


In this example, the figure titled The Default Keys was assigned the symbol- 
name of keyboard_fig in the tag <FIGURE>. The reference to this symbol- 
name does not contain a second argument, which means the writer accepts 
the default output. Therefore, if this reference and figure were to occur 

in a chapter numbered three, and would be the fourth formal figure, the 
paragraph containing the reference would have the following output: 


Figure 3-4 shows the keypad layout. 
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If the second argument to the <REFERENCE> tag was \FULL, the output 
would be as follows: 


Figure 3-4, The Default Keys shows the keypad layout. 


6.4.2 Referencing Symbol-Names in Other Files 


For text strings that you reference frequently in separate files of the same 
book, it is useful to place all of your <DEFINE_SYMBOL> and <DEFINE— 
BOOK_NAME> tags in one file, in a symbol definitions file. Then, to reference 
the symbol-names stored there, specify the name of the symbol definition file 
with the /SYMBOLS qualifier on the DOCUMENT command line when you 
process the file. 


For example, you could create a symbol definitions file named INTRO_ 
BOOK_SYMS.SDML. This file might contain the following symbol-names: 


<define_symbol>(PROGRAM_NAME\Matrix Maker) 
<define_symbol>(PROGRAM_VERSION\3. 2) 


When processing a file that references either of these symbols, you would 
specify the name of the symbol definitions file on the DOCUMENT command 
by typing the following line: 


$ DOCUMENT filename doctype destination /SYMBOLS=INTRO_BOOK_SYMS 


The /SYMBOLS qualifier assumes a filetype of .SDML by default. 





6.5 Creating a Preliminary Profile 
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Before you write your book, use the following procedure to make sure that 
your symbol-names will be referenced correctly in the entire book or in 
individual elements of the book. If you follow this procedure before you 
begin to write, your symbol-name references will be correct throughout the 
writing process. 


1. When the structure of the book is clearly defined, create a file for each 
element. All of the text need not be written. Use the <CHAPTER> or 
<APPENDIX> tags to head each element, and add <HEADx> tags if you 
have an outline of the chapter. The actual paragraphs of text can be filled 
in when you come to write the chapter. 


2 Create a profile that reflects the structure of the book. To do this, in 
a separate SDML file list all the files that are part of the book, tagging 
each file name in the list with an <ELEMENT> tag. In the front of the 
file, include the <PROFILE> tag, and at the end of the file, add the 
<ENDPROFILE> tag. Name this SDML file with any name that indicates 
it is a profile, for example, MYBOOK_PRO.SDML. 


Each <ELEMENT> tag should specify a file that contains a book element. 
No other files should be included in the profile. 


3 Process the profile to create the cross-reference file for the book. Indicate 
that you want to build the book by specifying the profile as the filename 
in the DOCUMENT command line. In this case, MYBOOK_—PRO.SDML 
is the name of the profile. 


$ DOCUMENT MYBOOK_PRO doctype destination 
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After completing this procedure, you have a complete cross-reference table of 
all your book element symbol-names. 





6.6 Adding New Symbol-Names 


As you write, you will probably add or delete tags that supply symbol-names. 
To reference new symbol-names and have each reference resolved correctly, 
you must rebuild the affected book elements as you go. You might want to 
rebuild any of the following: 


e An entire book (through a bookbuild) 
e An individual book element (through an element build) 


e A portion of a book element (through a subelement build) 
See Chapter 4 for the procedures for reprocessing files. 


Rebuilding an Entire Book 


You need to reprocess the entire book through a bookbuild only when you 
change the book in either of the following ways: 


e Reorder book elements that have incremental values associated with 
them, for example, reorder the chapters of the book 


e Add additional book elements that affect the numbering of other 
elements, for example, insert a new chapter 


Rebuilding an Individual Element of a Book 


To rebuild a file that contains one element of a book, use the /PROFILE 
qualifier on the DOCUMENT command line. The /PROFILE qualifier causes 
the tag translator to rebuild the cross-reference file with the newest symbol- 
names for that element. 


Rebuilding a Subelement of a Book 


Some books contain a large single element. The element might not be 
subdivided into chapters or appendixes, but instead consists of many 

pages of a highly structured reference section. Each item described in the 
reference section could be written as a separate SDML file, and it becomes 
convenient to process these files individually. In essence, you want to process 
a subelement of a book. 


To process a subelement, two qualifiers are added to the command line, 
/PROFILE and /ELEMENT. The tag translator processes the entire element 
through its first pass to correctly update the cross-reference file, but produces 
output only for the subelement that you specify as the input file on the 
DOCUMENT command line. 
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Generating a Table of Contents, Index, and 
Master Index 


This chapter describes how to create a table of contents, an index and a 
master index for your document. Complete reference information on the tags 
described in this chapter can be found in Chapter 9. 





Creating a Table of Contents 


You create a table of contents by specifying the /CONTENTS qualifer when 
you process your SDML file. VAX DOCUMENT automatically generates a 
table of contents entry for each of the following in your SDML file: 


e Appendixes, chapters, glossaries, indexes, parts, and prefaces 


e¢ Formal examples, figures, and tables (if specified with a caption or a 
symbol-name argument) 


¢ Numbered heading tags (table of contents entries for the <HEAD5> and 
<HEAD6> tags are doctype-dependent) 


e SOFTWARE doctype reference-element tags: <COMMAND> , 
<ROUTINE> , <SDML_TAG>, <STATEMENT> , and <FUNCTION> 


¢ SOFTWARE doctype subcommand tags: <SUBCOMMAND> and 
<SUBCOMMAND-_SECTION_HEAD> 


e REPORT doctype <SECTION> tag 


See the table of contents in this manual for a sample of a table of contents 
created by VAX DOCUMENT. 


The table of contents is created during the text formatting of your document. 
If you omit text formatting by using the /NOTEXT_FORMATTER qualifier, 
contents generation is also omitted. If you use the /CONTENTS and 
/NOTEXT_FORMATTER qualifiers together, VAX DOCUMENT issues an 
error message. 


VAX DOCUMENT creates a separate file for the table of contents. It names 
this file by taking the file name of the input-file-spec parameter you specify 
on the DOCUMENT command line and appending “_CONTENTS?” to it. You 
need do nothing more than specify /CONTENTS on the command line if 
you want to maintain your table of contents in a separate file; however, if 
you want this file automatically incorporated into your document, use the 
<CONTENTS_FILE> tag in your SDML file. 


When the <CONTENTS_FILE> tag is processed by VAX DOCUMENT, 

the latest table of contents file is incorporated into the final output file 
where the <CONTENTS_FILE> tag occurs in the SDML file. If you use the 
/NODEVICE_CONVERTER qualifier, the table of contents will not be 
incorporated into your file. 
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You can make sure that the latest version of the table of contents is 
incorporated into your file by specifying the /CONTENTS qualifier whenever 
you process a file that contains the <CONTENTS_FILE> tag. This action 
guarantees that the table of contents file correctly reflects the organization 
and pagination of your SDML file. If you do not specify /CONTENTS, an 
out of date table of contents may be included into your document. 


When you create a table of contents using the /CONTENTS qualifier, 
whatever parameters and other qualifiers you specify affect the processing 
of both the table of contents file and your SDML file. For example, if 
the LNO3 destination and the /NOPRINT qualifier are specified, both 
files are formatted for the LNO3 laser printer (input-filename.LNO3 and 
input-filename_CONTENTS.LNO3) but neither is printed. 


The following example shows how a table of contents may be created along 
with the output of the file MYREPORT.SDML: 


$ DOCUMENT myreport REPORT LNO3 /CONTENTS 


The table of contents generated by the previous command would be 
MYREPORT_CONTENTS.LNO3. 





7.2 Creating an Index 


You can automatically generate an index file from your SDML file by using 
the /INDEX qualifier to the DOCUMENT command. To create an index 
using VAX DOCUMENT, you mark the text elements within your SDML file 
that you want included in your index with <x> and <yY> tags, and then 
you process your SDML file using the /INDEX qualifier to generate an index 
file from your SDML file. 


The <X> tag is used to create main entries in the index. Main entries have 
page numbers associated with them. The <yY> tag is used to create cross- 
reference entries in the index. Cross-reference entries (also called “See” or 
“See also” entries) do not have page numbers associated with them, instead 
they refer the reader to a main entry in the index. 


Both <x> and <yY> tags can have subentries (also called subheadings or 
modifications), which are index entries that are indented under either a main 
entry created using the <X> tag, or a cross-reference created using the <y> 
tag. 


The following example shows a part of an SDML file that contains <x> and 
<Y> tags. The <XSUBENTRY> tag is used to create subentries in both tags. 
<headi>(Usage of Official Vehicles) 

<X>(Vehicles<XSUBENTRY>usage of) 

<Y>(CORP-AUTO report<XSUBENTRY>See Vehicles) 

<p> 

Official vehicle usage is listed in a separate report CORP-AUTO-1439u2. 

This report is organized as in the following outline. 


If these tags occurred on page 3-1, they would create the following index 
entries (under the headings “-C-” and “-V-”, respectively): 


CORP_AUTO 
See Vehicles 
Vehicles 


usage of, 3-1 


Generating a Table of Contents, Index, and Master Index 


See the index in this manual for an example of an index produced using VAX 
DOCUMENT. 


The following example shows a command line that will create an index file 
along with the output of the file MYREPORT.SDML: 


$ DOCUMENT myreport.sdml REPORT LNO3 /INDEX 


You can tailor your index in several ways by using the arguments and 
keywords explained later in this chapter, or you can accept the VAX 
DOCUMENT default index file characteristics. The following list describes 
the default characteristics of an index file: 


Capitalization of index entries is retained in the index as entered. 


Index entries are formatted in two columns on each page. On the last 
page the entries are balanced so that the two columns are of equal length. 


Guide headings are automatically inserted into the index before each 
entry that begins a new alphabetic section. For example, when the 

first index entry beginning with the letter “B” is encountered, the guide 
heading “-B-” is placed before it. The exact format of the guide heading 
is doctype-dependent. 


Index entries are sorted in the index according to the following default 
rules: 


— Entries with all nonalphabetic characters are placed before all other 
entries. . 


— Entries beginning with nonalphabetic characters are sorted by the 
alphabetic characters following the nonalphabetic characters. 


— Entries are sorted on a word-by-word basis in which spaces and 
hyphens are treated as significant sorting characters. 


— Index entries generated by the <yY> tag are placed at the beginning 
of each subentry level. This is done on the assumption that cross- 
reference information should be positioned at the top of each 
subentry level so that the user can find it easily. 


Index entries are merged only when they have identical spelling, spacing, 
emphasis, and capitalization in the SDML file. Page-number references 
are merged only if they refer to the same page and are specified with 
identical attributes such as emphasis and appended text. Even if index 
entries or page numbers look identical on the printed page, they will not 
be merged unless they are coded identically in the SDML file. 


For example, the entries <X> (<TAG> (LINE)) and 

<X> ( <TAG> (line)) would appear the same on the printed page 
because the <TAG> tag would format both tag-names in uppercase 
characters. However, these entries would create separate index entries 
because the tag-name is not capitalized consistently in the SDML code for 
both entries. 
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e Either a bullet (e) or a comma (,) is placed between each index entry and 


its first page reference. The character used for punctuation is doctype- 
dependent. For example, if the doctype specifies that commas are to be 
used, the entry appears as follows: 
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If a main level index entry is followed by a subentry rather than a page 
reference, no punctuation is placed after the main entry. Instead, the 
punctuation is placed after the subentry to set off the page reference as in 
the following example: 
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description, 4-10 
examples, 4-12 


7.2.1 Creating Main Index Entries 


Use the <X> tag to create a main index entry. The <x> tag places an entry 
in the index that contains the page number of the output page on which this 
tag occurs. For example, if the <x> tag in your SDML file is processed while 
page 2-132 is being created by the text formatter, the index entry from that 
<x> tag would reference page 2-132. 


The <x> tag has the following syntax: 


<X> (index-entry[\attribute]) 


Use the index-entry argument to supply the text for the main entry and 
subentries in the index. The text used in this argument is placed in the index 
entry exactly as entered, including any capitalization. Use the <XSUBENTRY> 
tag within this argument to separate the main entry from the first subentry, 
and the second subentry from the first, as follows: 


<X> (Main entry <XSUBENTRY> subentry-1 <XSUBENTRY > subentry-2) 


The <XSUBENTRY> tag can be abbreviated as <xS>. You can use no more 
than three subentries in an index. 


Use the attribute arguments to control the sorting and formatting of the 
index entry. You can specify up to five attribute arguments to the <x> tag. 
Section 7.2.2 describes the indexing tag attributes. 


Use the following <x> tag coding rules to ensure that the page references in 
your main index entries are correct: 


e Place <x> tags after tags in your SDML file that are likely to begin a 
new page, such as <CHAPTER> or <HEADI>. 


e Index entries that are to be merged in the index should be coded 
identically in the SDML file, including emphasis, capitalization, spacing 
and spelling. 


e When inserting <x> tags into tables, place the <x> tags within the 
arguments to the <TABLE_ROW> tag, so that the page references will be 
correct if the text formatter breaks the table across pages. 
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¢ Do not place <x> tags within examples. Doing so may interfere with 
the formatting of the examples. 

The following example shows the correct positioning of the <x> tag that 

provides an indexing entry for a chapter: 

<CHAPTER> (Creating Routines\creating_routine_sec) 

<X>(Routines<XSUBENTRY>creation of) 

<P> 


In order to create a routine, you must first 


If the previous text appeared on page 11-2, this <x> tag would create the 
following index entry: 


Routines 


creation of, 11-2 


7.2.2 Using Indexing Tag Attributes 


7.2.2.1 


The attribute arguments to the <xX> and <yY> tags control the sorting 

and formatting of individual index entries. These attributes are described 
alphabetically in the following sections. All of these attributes can be used 
with the <Xx> tag; however, only the MASTER and <xSORT> attributes can 
be used with the <y> tag. 


Using the BEGIN and END Attributes 

Use the BEGIN and END attributes to create an index entry for consecutive 
pages. These attributes create an index entry with a page range such as 
“System Concepts, 12-3 to 12-7.” When you use a BEGIN and END pair, the 
index entries and indexing attributes you specify must be identical for the 
index entries to be sorted correctly. 


The following example shows how a page range can be coded using the 
BEGIN and END attributes. In this example, the tag with the BEGIN attribute 
is processed on page 12-3 and the tag with the END attribute is processed on 
page 12-7. 

<HEAD1>(Concepts of the System\sys_con) 


<X> (System Concepts\BEGIN) 
<P> 


<X>(System Concepts\END) 
<HEAD1>(Using the System\sys_using) 


These index tags would create a page range as follows: 


System Concepts, 12-3 to 12-7 


<xX> tags that occur between a BEGIN and END pair that have entry 
text identical to that of the BEGIN and END pair are ignored, and VAX 
DOCUMENT issues an informational message stating that this index entry 
was ignored when it creates the index. 


For example, if an index entry for “System Concepts” was processed on 
output page 12-4, between the index entries specified with the BEGIN and 
END attributes in the previous example, the code would appear as in the 
following example: 
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7.2.2.2 


7.2.2.3 


<X>(System Concepts\BEGIN) 


<X>(System Concepts) 
<X>(System Concepts<XS>entering files) 


<X> (System Concepts\END) 
These index tags would create the following index entry: 


System Concepts, 12-3 to 12-7 
entering files, 12-4 


The <x> (System Concepts) tag on page 12-4 would be ignored, and VAX 
DOCUMENT would issue an informational message about that tag when 
it creates the index. Note that the <x> tag whose entry text included the 
subentry “entering files” was not ignored during the creation of the index. 


Using the BOLD Attribute 

Use the BOLD attribute to cause page numbers to appear in bold type in your 
index. If both the BOLD and ITALIC attributes are specified, the page number 
will be output in bold italic type. 


Page number references that are output in a bold type face using the BOLD 

attribute are sorted as being distinct from page number references that are 

output in a bold type face using some other means (such as the global 
<EMPHASIS> ( \BOLD) tag). 


The following is an example of an <xX> tag that uses the BOLD attribute: 
<X>(System Concepts \BOLD) 


If this index tag occurred on page 12-3, it would create an entry in the index 
as follows: 


System Concepts, 12-3 
Using the ITALIC Attribute 
Use the ITALIC attribute to cause page numbers to appear in italic type in 


your index. If both BOLD and ITALIC are specified, the page number will be 
output in bold italic type. 


Page number references that are output in an italic type face using the ITALIC 
attribute are sorted as being distinct from page number references that are 
output in an italic type face using some other means (such as the global 
<EMPHASIS> tag). 


The following is an example of an <xX> tag that uses the ITALIC attribute: 
<X> (System Formats\ITALIC) 


If this index tag occurred on page 6-11, it would create an entry in the index 
as follows: 


System Concepts, 6-11 


7.2.2.4 


7.2.2.5 


7.2.2.6 
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Using the MASTER Attribute 

Use the MASTER attribute to specify an index entry that you want to appear 
in a master index. The following is an example of an <X> tag that uses the 
MASTER attribute: 


<X>(System formats\MASTER) 


By default, entries labeled with the MASTER attribute are included only in 
the master index and entries not labeled with the MASTER attribute are 
included only in the index of a single document. 


You can override these defaults by using the following DOCUMENT 
command line qualifiers: 


/INDEX=OVERRIDE_MASTER Creates a single document index containing 
both master and nonmaster index entries. 

/MASTER_INDEX=OVERRIDE_ Creates a master index containing both 

MASTER master and nonmaster index entries. 


See Section 7.2.5 for more information on the OVERRIDE_MASTER 
keyword. See Section 7.3 for information on creating a master index. 


Using the <XAPPEND> Attribute | 

Use the <XAPPEND> attribute to append a specified string to the end of a 
main entry page reference. You append the string by passing that string as 
an argument to the <XAPPEND> attribute as <XAPPEND> (string). Use the 
<XAPPEND> attribute to add information to a main index entry, for example, 
to mark an index page as referring to a table (9-8tab) or to insert common 
indexing terms such as “page 3ff” or “5-3 to 5-6 passim.” 


The following example shows an <X> tag that appends the string “ff” to the 
page reference using the <XAPPEND> attribute: 


<X>(File structure\<XAPPEND> (ff) ) 


If this tag were processed on page 3, this tag would create the following main 
index entry: 


File structure, 3ff 


Using the <XSORT> Attribute 

Use the <XSORT> attribute to control the default sorting of individual index 
entries. For example, if you wanted the entry “$$” to appear in your index 
sorted as the words “double dollar,” you could place the <XxXSORT> tag in. 
your SDML file as follows: 


<X>($$\<XSORT>(double dollar) ) 


This attribute is especially useful for overriding the default sorting of leading 
nonalphabetic characters in individual index entries. 


Generating a Table of Contents, Index, and Master Index 


7.2.3 Creating Cross-Reference Index Entries 


The <yY> tag creates an entry in an index file that has no output page 
associated with it. This tag is typically used to create cross-references to other 
index entries (“See” or “See also” entries). The <y> tag has the following 
syntax: 


<Y> (index-entry[\attribute]) 


The <yY> tag accepts the same index-entry argument as the <x> tag. Index 
subentries are specified within the index-entry using the <XSUBENTRY> 
(abbreviated as <XS> ) tag just as for the <x> tag. The <yY> tag accepts 
only the MASTER and <xXSORT> indexing tag attributes because all other 
attributes are for manipulating page numbers. 


MASTER indicates that the index entry should only occur in the master index 
and <XSORT> lets you override the sorting algorithm for an individual entry. 
See Section 7.2.1 for more information on these attibutes. Section 7.2.2 
describes the indexing tag attributes. 


The following example shows the <yY> tag used with the <x> tag. The 
<X> tag creates an index entry with a page number reference and the <yY> 
tag creates a “See also” index entry: 


<X>(File structure designators) 
<Y>(File structure designators<XSUBENTRY>See also Header blocks) 


These indexing tags create the following index entry (assuming these tags 
appeared on page 1-3): 


File stucture designators, 1-3 
See also Header blocks 


7.2.4 Processing an Index 


When you use the DOCUMENT /INDEX qualifier, VAX DOCUMENT 
processes the index entries you created in your SDML file, and places them 
in a separate index file. VAX DOCUMENT names this file by taking the 
file name of the input-file-spec parameter you specified on the DOCUMENT 
command line and appending “_INDEX” to it. 


If you omit text formatting by using the /NOTEXT_FORMATTER qualifier, 
index processing will also be omitted, because the index is processed during 
text formatting. If you use the /INDEX and /NOTEXT_FORMATTER 
qualifiers together, VAX DOCUMENT issues an error message. 


You need do nothing more than specify /INDEX on the command line if you 
want to maintain your index in a separate file; however, if you want this file 
automatically incorporated into your document, place the <INDEX_FILE> tag 
in your SDML file. 


When the <INDEX_FILE> tag is processed by VAX DOCUMENT, the latest 
index file is incorporated into the final output file where the <INDEX_FILE> 
tag occurs in the SDML file. If you use the /NODEVICE_CONVERTER 
qualifier, the index will not be incorporated into your file. 
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Use the /INDEX qualifier whenever you process a file that contains the 
<INDEX_FILE> tag to make sure that the latest version of the index is 
incorporated into your file. This action ensures that the index file correctly 
reflects the organization and pagination of your SDML file. If you do not 
specify /INDEX, an out of date index may be included into your document. 


When you create an index using the /INDEX qualifier, whatever parameters 
and other qualifiers you specify affect the processing of both the index file 
and your SDML file. For example, if you specify LNO3 as a destination and 
also use the /PRINT qualifier, both files will be printed on the LNO3 laser 
printer (input-filename.LNO3 and input-filename_INDEX.LNO3). 


The following example shows how an index may be created and printed 
using the /INDEX and /PRINT qualifiers. Both the SDML file (MYREPORT) 
and the index file created from that SDML file (MYREPORT_INDEX) are 
formatted for the LNO3 laser printer and printed on it as specified on the 
command line. VAX DOCUMENT concatenates the printing of the two files 
into a single print job so VMS issues only one print message. 


$ DOCUMENT myreport.sdml REPORT LNO3 /INDEX /PRINT=(NOTIFY) 
%DOC-I-IDENT, VAX DOCUMENT 1.1 


(Tag Translation]... 

“%TAG-I-DEFSLOADD, End of Loading of Tag Definitions 
“%TAG-I-ENDPASS_1, End of first pass over the input 
[Text Formatting]... 

“%,TEX-I-PAGESOUT, 17 pages written. 

-TEX-I-QUTFILENAME, 'DUA1: [DOCFILES]MYREPORT.DVI_LNO3' 
[Index Generation] 


“%INX-I-ENDPASS_1, End of first pass over input file: 
'DUA1: [DOCFILES] MYREPORT_INDEX.INX' 
%INX-I-ENDPASS_2, End of second pass over input file. 


%INX-I-CREATED, 'DUA1: [DOCFILES]MYREPORT_INDEX.TEX;1' created 
(Text Formatting Index]... 
%TEX-I-PAGESOUT, 1 page written. 
~TEX-I-QUTFILENAME, 'DUA1: {[DOCFILES]MYREPORT_INDEX.DVI_LNO3' 
[Device Conversion]... 
#DVC-I-PAGESOUT, 18 pages written to file: 

DUA1: [DOCFILES]MYREPORT . LNO3 
[Index Device Conversion]... 
%DVC-I-PAGESOUT, 1 page written to file: 

DUA1 : [DOCFILES] MYREPORT_INDEX .LNO3 
[Printing File]... 
[Printing Index]... 


Job MYREPORT (queue SYS$LNO3, entry 835) started on SYS$LNO3 


$ 


7.2.5 Using Indexing Options 


The following subsections describe the optional keywords. that can be used 
with the /INDEX and /MASTER—INDEX qualifiers; the keywords have the 
same meanings for both qualifiers except where noted. 


These keywords allow you to control whether guide headings are used, how 
master index entries should be processed, and how index entries should be 
sorted. The indexing option keywords are as follows: 


e [NO]GUIDE_HEADINGS 


¢ [NOJOVERRIDE_MASTER 
¢ SORT 
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These keywords are described alphabetically in the following subsections, and 
are specified as follows: 


/INDEX[=(index-keyword [,index-keyword...])] 
/MASTER_INDEX[=(index-keyword [,index-keyword...])] 


7.2.5.1 Using the GUIDE_HEADINGS and NOGUIDE—HEADINGS Keywords 
Use the GUIDE_HEADINGS and NOGUIDE—HEADINGS keywords to 
specify whether alphabetic headings are inserted into the index whenever an 
entry beginning with a new letter occurs. The GUIDE_HEADINGS keyword 
is the default. 


For example, when the first index entry beginning with the letter “B” is 
encountered, the guide heading “-B-” is placed before it. 


NOGUIDE_HEADINGS suppresses guide headings in the index output file. 


7.2.5.2 Using the OVERRIDE_MASTER and NOOVERRIDE_MASTER 
Keywords 
The OVERRIDE_MASTER and NOOVERRIDE_MASTER keywords specify 
how index entries with and without the MASTER attribute are included in a 
single document index and a master index. 


e Use /INDEX=NOOVERRIDE—MASTER to create a single document 
index that contains only the index entries that are not marked with the 
MASTER keyword; this is the default. 


e Use /INDEX=OVERRIDE—MASTER to create a single document index 
that contains both the index entries that are not marked with the 
MASTER keyword and the entries that are marked with the MASTER 
keyword. 


e Use /MASTER_INDEX=NOOVERRIDE—MASTER to create a master 
index that contains only the index entries that are marked with the 
MASTER keyword; this is the default. 


e Use /MASTER_INDEX=OVERRIDE_MASTER to create a master index 
that contains both the index entries that are not marked with the 
MASTER keyword and those entries that are marked with the MASTER 
keyword. 


7.2.5.3 Using the SORT Keyword 
Use the SORT keyword to specify the sorting algorithm used to order entries 
in an index. The SORT keyword has the following syntax: 


SORT(|=sort-keyword[,sort-keyword[=value]]] 


The following are valid sort-keywords: 


e SORT=LETTER sorts the entries letter-by-letter and ignores spaces and 
hyphens. SORT=LETTER is the default. 


For example the entry “A directory” would be sorted after the entry 
“Add,” because the space is ignored in the sorting and so “A di” is placed 
after “Add” by the sort. 


¢ SORT=WORD sorts the entries letter-by-letter and treats spaces and 
hyphens as significant. 
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For example the entry “A directory” would be sorted with other entries 
that began with “A d” rather than with the entry “Add” because the 
space is treated as a significant part of the entry during the sorting; this 
results in “A d” being placed before “Add” by the sort (because by default 
nonalphabetic characters are sorted before alphabetic characters). 


SORT=NONALPHA positions entries with initial nonalphanumeric 
characters in the index based on the following keyword, supplied with 
the NONALPHA keyword: 


— The AFTER keyword causes entries with initial nonalphanumeric 
characters to be placed at the end of the index. 


— The BEFORE keyword causes entries with initial nonalphanumeric 
characters to be placed at the beginning of the index. 


— The IGNORE keyword causes entries with initial nonalphanumeric 
characters to be sorted by the first alphanumeric characters in the 
entry. The default is NONALPHA=IGNORE. 





7.3 Creating a Master Index 


VAX DOCUMENT lets you combine the indexes from several documents to 
create a master index for a documentation set. This master index has the 
same format as that of a single-document index, with the following additions: 


Master index entries are cited both by the title of the document from 
which they originated and by page number. Document titles are italicized 
in these index entries. 


Index entries that were specified using the MASTER keyword attribute in 
individual documents are automatically entered into the master index. 


You can modify your master index by specifying indexing option keywords. 
The /MASTER_INDEX qualifier accepts the same indexing option keywords 
as the /INDEX qualifier. See Section 7.2.5 for more information on the 
indexing option keywords. 


You create a master index by performing the following steps: 


1 


2 


Create individual intermediate index (INX) files using the /INDEX and 
/KEEP=(INX) qualifiers to the DOCUMENT command. 


Create a master index data file, which lists each of the intermediate index 
files with the title of the book from which the index file was generated. 


Run VAX DOCUMENT using the /MASTER_INDEX qualifier and 
specifying the master data file as the input-file-spec parameter. 


This will produce a final printable master index file with the same file 
name as the master data file and with a file type associated with the 
destination keyword specified on the command line (for example, LNO3). 
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7.3.1 Creating Intermediate Index Files 


You create intermediate index files whenever you use the /INDEX qualifier to 
create an index. However, VAX DOCUMENT deletes these files unless you 
also specify the /KEEP specifier with the INX keyword argument. You can 
specify these qualifiers, as in the following example: 


$ DOCUMENT mychapter.sdml REPORT LNO3 /INDEX /KEEP=(INX) 


7.3.2 Creating the Master Index Data File 


You create the master index data file just as you would create any ASCII 
file (by using an editor, using the VMS CREATE command, and so on). The 
master index data file lists all the index files that are to be collated into the 
master index. Give the master index data file a unique file name. When you 
use the master index data file as the source file for your master index, the 
DOCUMENT command will expect a default file type of INX_LIST. 


Each master: index entry is associated with the book that it came from. 

You can use the /BOOK_IDENTIFIER qualifier inside of the data file to 
specify the title of that book. If you do not specify the /BOOK_IDENTIFIER 
qualifier, the title of the book will be the file name of the INX file. The 
/BOOK_IDENTIFIER qualifier has the following syntax: 


/BOOK_IDENTIFIER="book-title” 


If you specify the /BOOK_IDENTIFIER without the book-title value, VAX 
DOCUMENT issues an error message. If you want to generate a master index 
without book titles, you can specify null strings to the /BOOK_IDENTIFIER 
qualifier for all your intermediate index files as follows: 


2041.INX/BOOK_IDENTIFIER="_" 
2323. INX/BOOK_IDENTIFIER="_" 


Use the following rules in entering intermediate index file specifications 
(filename.INX files) into the master index data file: 


e Each index file specification must be entered on a single line in the data 
file with no other characters preceding it. 


e Each index file specification must be an intermediate indexing file 
(filename.INX) and must be specified completely including the INX 
file type. You can also use a process logical name for the intermediate 
indexing file. 


e Comments can be made in the data file using the exclamation point (!) 
character. This character excludes from processing only those characters 
that follow it on the same line. 


The following is a sample of a master index data file. Because the books listed 
in this file all have numeric names, the /BOOK—IDENTIFIER qualifier was 
used to specify more meaningful book titles. 


Generating a Table of Contents, Index, and Master Index 


'Master index data file 
!Created Dec 1, 1986 
{Updated Jan 4, 1987 

! 


2041. INX/BOOK_IDENTIFIER="System Generation" 
2323. INX/BOOK_IDENTIFIER="Writing I/O Driver" 
2050. INX/BOOK_IDENTIFIER="MCR Operations" 
2053. INX/BOOK_IDENTIFIER="Program Development" 
2054. INX/BOOK_IDENTIFIER="Executive" 

2055. INX/BOOK_IDENTIFIER="Task Builder" 

2056. INX/BOOK_IDENTIFIER="System Library" 

2057 . INX/BOOK_IDENTIFIER="Utilities" 

2059. INX/BOOK_IDENTIFIER="I/0 Drivers" 

2176. INX/BOOK_IDENTIFIER="Release Notes" 


7.3.3 Creating the Master Index File 


You create the printable master index file by running the DOCUMENT 
command with the /MASTER_INDEX qualifier and specifying the master 
index data file as the input-file-spec parameter. The master data file has a 
default file type of INX_LIST. 


In the following example, the master index data file MYMASTER.INX— 
LIST is processed using the /MASTER_INDEX qualifier to create the file 
MYMASTERINDEX.LNO3: 


$ DOCUMENT MYMASTER.INX_LIST REPORT LNO3 /MASTER_INDEX 

%DOC-I-IDENT, VAX DOCUMENT V1.1 

[Master Index Generation]... 

%INX-I-ENDPASS_1, End of first pass over input file: 
"DUAL: [DOCFILES] 2041. INX' 

%INX-I-ENDPASS_2, End of second pass over input file. 

“%INX-I-ENDPASS_1, End of first pass over input file: 
'DUA1: [DOCFILES] 2323. INX' 

“INX-I-ENDPASS_2, End of second pass over input file. 

%INX-I-ENDPASS_1, End of first pass over input file: 
'DUA1: [DOCFILES] 2050. INX' 

%INX-I-ENDPASS_2, End of second pass over input file. 

%INX-S-CREATED, 'DUA1: [DOCFILES]MYMASTER.TEX;1' created 

[Text Formatting]... 

“%TEX-I-PAGESOUT, 8 pages written. 


-TEX-I-QUTFILENAME, 'DUA1: [DOCFILES]MYMASTER.DVI_LNO3' 
[Device Conversion]... 
%DVC-I-PAGESOUT, 18 pages written to file: 

DUA1 : [DOCFILES] MYMASTER . LNO3 
LPrietamege “Fi lecTun. 


Job MYMASTER (queue SYS$LNO3, entry 835) started on LNO3 


$ 
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| S Special Features 


This chapter describes various special features that you can request in the 
formatted output. The features include the following: 


e Providing emphasis, such as bolding or italicizing 
e Using footnotes 

e §=Using callouts 

e Drawing large braces and brackets 

¢ Controlling case 

e Formatting mathematical formulas 

e Providing quotation marks 

e Placing parentheses around a single character 


e Drawing horizontal and vertical ellipses 





8.1 Providing Emphasis 


There are numerous methods available to lend emphasis to words or phrases 
in your printed output. In most methods, you pass the text to be emphasized 
as an argument to a special tag. 


This section discusses the tags as global tags, because they are always 
available for use. The formatted effect of each tag is also described here, 
but you should be aware that the effect can differ depending on the doctype. 


The <EMPHASIS> tag provides italic or bolding emphasis. At first glance, 
those capabilities would seem to be adequate for most purposes, but in fact 
there are many additional tags that provide emphasis. The variety of tags 
relates to the numerous possible reasons for emphasis. 


The reasons vary: the word might be the name of something, it might be 

a reserved word in a programming language, or it might be being used for 
the first time in your book. In a generic markup language, you should be 
tagging the word according to the reason for its emphasis, not according to 
the desired effect in the formatted output. In other words, you should be 
thinking, “This is the first use of this phrase,” and not thinking, “This phrase 
needs to be italicized.” 


Accordingly, the tags for emphasis attempt to name the reason for the 
emphasis rather than to name the formatting effect. If you use the tags 
properly in your SDML files, the book designer is free to change the effect 
for a single tag. Thus, the tag that lends emphasis to a first-time use, 
<NEWTERM> , might be changed from simple italic to an italic font that is 
larger or bolder. However, another tag that also gives an italic effect might be 
left unchanged. If you fail to distinguish these two uses when you code the 
SDML file (by coding both with the <EMPHASIS> tag), you will not be able 
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to make a selective change in the type of emphasis for the <NEWTERM> tag 
without affecting your output. 


A description of each of the emphasis tags follows: 


Note: 


<GREF> and <NEWTERM> 


These two tags are similar, in that they are used to refer to a word or 
phrase in a special first-time use, where the word is about to be defined. 
Use the <GREF> tag if the word is also in the glossary. 


<KEYWORD> 


Use this tag in a discussion of a word or phrase from a computer program 
or a programming language (sometimes called a “reserved word”). 


<VARIABLE> 


When you write about the effect of executing some computer program 
command or programming language statement, you may want to refer to 
a variable by name and then refer to its value. Tagging the variable name 
with this tag ensures that it has the proper emphasis in the output. 


<EMPHASIS> and <UNDERLINE> 


These tags are appropriate for situations where the other emphasis tags 
are unsuitable. Because they specify the formatting effect in the output 
rather than the reason for the effect, use them sparingly. 


<NOTE> 


This tag has a pronounced formatting effect, because it not only bolds 
the text, but it breaks the text out of its surrounding text and supplies an 
attention-getting heading. An example of an appropriate use follows: 
the unary minus in this expression. 
<NOTE>Observe how the precedence of the unary minus operator 
requires the use of parentheses in this expression. 
<ENDNOTE> 
This example might produce the following: 


... the unary minus in this expression. 


Observe how the precedence of the unary minus operator requires the 
use of parentheses in this expression. 


Table 8-1 shows each of the tags (except <NOTE> ) used in text. Your output 
might differ, according to the design chosen for your system. 
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Table 8—1 Examples of Emphasis Tags 


Coding Output’ 

The <GREF> (abc def) letters The abc def letters 
The <NEWTERM> (abc def) letters The abc def tetters 
The <KEYWORD> (abc def) letters The abc def letters 
The <VARIABLE> (abc def) letters The abc def letters 
The <EMPHASIS> (abc def) letters The abc def letters 
The <EMPHASIS> (abc def\BOLD) letters The abc def letters 
The <EMPHASIS> (abc def\SMALLCAPS) letters The ABC DEF letters 
The <EMPHASIS> (abc def\SMALL_—BOLDCAPS) The asc ber letters 

letters 

The <UNDERLINE> (abc def) letters The abc def letters 


'The output of the samples included in this table is dependent on the doctype 
and printing device used. 


As you read about each tag, remember that the punctuation that follows a 
bolded or italic font should be printed in the same font. This means that you 
should always include the punctuation as part of the argument. 





8.2 Using Footnotes 


Three tags are available for creating a footnote, the <FOOTNOTE> ‘tag, the 
<FOOTNOTE_TEXT> tag, and the <FOOTREF> tag. Their syntax is as follows: 


<FOOTNOTE> (char\footnote-text) 
<FOOTNOTE_TEXT> (char\text) 
<FOOTREF>(char-1[\char-2...\char-9]) 


A footnote consists of two parts, the character that appears as a small 
superscript in the text, and the correspondingly noted sentence or paragraph 
at the foot of the same page. The <FOOTNOTE> tag provides both the 
superscript and the actual text. 


You supply the superscript character as the first argument of the 
<FOOTNOTE> tag and the footnote text as its second argument. Place 

the <FOOTNOTE> tag precisely where you want the number to appear. This 
is generally at the end of a phrase or sentence and usually after the closing 
punctuation. Do not leave space between the punctuation and the opening 
angle bracket of the <FOOTNOTE> tag. 


VAX DOCUMENT places the character as a small superscript in the text, and 
floats the text to the foot of the page. 


You can use the <FOOTREF> tag to place the same number at another place 
in the text, although this practice is discouraged. 


Use the <FOOTNOTE> and <FOOTREF> tags to create footnotes in tables. 
Table footnotes appear at the foot of the table, rather than at the foot of the 
page. When you need a footnote in a table, place the <FOOTNOTE> tag at 
the beginning of the table immediately after the <TABLE_SETUP> tag. Then, 
at the desired points within the table, supply the <FOOTREF> tag. With this 
method, you can place the same superscript at more than one point in the 
table. 
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Special Features 


Using Callouts 


For multipage tables, the footnote text repeats on each page that carries a 
reference to that note, provided that you call the footnotes out in the table 
heading. If the reference is in the heading, the footnotes and references 
appear on all pages of the table. 


The output device must have a character font that displays these superscript 
characters. 


The <FOOTNOTE_TEXT> tag is necessary when a footnote must be provided 
on a title or copyright page or in the context of header-level text. 





Three tags are available for annotating examples by what is termed a callout. 
The callout is a number that draws special attention, possibly by being 
printed as a white digit on a black background, for example @, or through 
some other graphic display. Writers frequently display numbers this way to 
mark points in an example that are then explained by entries in a numbered 
list that follows the example. The numbers of the list entries are displayed in 
the same format (white digit on a black background). 


Callouts are used within a restricted area of the SDML file that you indicate 
by <CALLOUTS> and <ENDCALLOUTS> tags. Within the example or text that 
is to be annotated, you locate the desired numbers by using the <CO> tag 
with the correct number as its argument. Following the area of the callouts, 
you supply the list of explanations or notes by introducing the list with the 
<LIST> (CALLOUT) tag. The list entries are introduced by the <LE> tag 
and the list is ended with the <ENDLIST> tag. However, when the list is 
formatted, the number of each entry in a noted-list is displayed as a white 
number on a black background. 


When you begin an example that will include callouts, you can specify 
\PREFIX as an argument of the <CALLOUTS> tag. This causes the example 
to be indented, leaving a gutter on the left. Then, if you specify the <co> 
tag at the left end of an example line, the callout number will be placed in 
the left gutter. In this way, VAX DOCUMENT does not disturb the normal 
indentation that might be important in your example. Here are two identical 
example lines, coded as follows: 


<CO>(2)PROGRAM Calculator (INPUT, OUTPUT); 
TYPE 
Yes_No = (Yes, No); 


Without the \PREFIX argument, the output format is as follows: 


@pROGRAM Calculator (INPUT, OUTPUT) ; 
TYPE 
Yes_No = (Yes, No); 


With the \PREFIX argument, the output format is as follows: 


2) PROGRAM Calculator (INPUT, OUTPUT); 
TYPE 
Yes_No = (Yes, No); 


Callouts are not limited to use within monospaced examples. For example, 
if you want to number certain paragraphs of text, or if you want to place 
callouts into a template to distinguish one group of entries from another, 
you can surround the area with the <CALLOUTS> ... <ENDCALLOUTS> 
tags and then place the <CO> tags wherever numbers are desired. For text 
paragraphs, you must be sure to place the <CO> tag after the <P> tag 
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that starts a paragraph, and in other cases you may have to place the <CO> 
tag within an argument list so that the callout number is associated with the 
proper text elements. If you use the \PREFIX argument on the <CALLOUTS> 
tag when you put callouts on paragraphs, the paragraphs are not indented, 
but the callout number is pushed to the left of the normal text margin, as 
follows: 


@ This is a paragraph with a callout. The \PREFIX argument was used on the 
<CALLOUTS> tag. 


If you need to refer to a noted-list entry, you should use the <CALLOUT_ 
REF> (callout-number) tag. This tag need not occur within the 
<CALLOUTS> ... <ENDCALLOUTS> tags. The word “callout” is editorial 
jargon and is probably not in your reader’s vocabulary, so do not write “see 
callout ©.” Instead, refer to the numbered item as a note. For example, “see 
note ©.” 


Each device treats callouts in a distinct way typographically. This might vary 
from device to device according to the available fonts. 





8.4 Drawing Large Braces and Brackets 


When you are documenting the syntax of a programming language, you often 
use the convention that shows choices (or options) as items that are vertically 
stacked inside large brackets or braces. You tell:the reader that the brackets 
mean an optional choice and the braces mean a required choice. _ 


These brackets or braces are produced in the output by using the 

<LIST> (STACKED) tag. The <LIST> (STACKED) tag works like other list 
tags in that the list begins with the <LIST> tag, each element is introduced 
by the <LE> tag, and the list is ended by the <ENDLIST> tag. The size of 
the bracket or brace is adjusted automatically to enclose the list elements and 
the enclosed list is aligned with other elements on the same line. Here is an 
SDML file excerpt: 


<P> 

SET 

<LIST> (STACKED\BRACES) 
<LE>LOZENGE 
<LE>UNDERSCORE 
<LE>GRAPHIC 

<ENDLIST> 

CURSOR 

<LIST> (STACKED\BRACKETS) 
<LE>ON 

<LE>OFF 

<ENDLIST> 

(Default is ON) 


The result is as follows: 


LOZENGE at 
SET « UNDERSCORE CURSOR | | Default is ON) 


GRAPHIC i 
The output device must have a character font that displays these braces and 
brackets. 
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Controlling Case 


Usually, you control the case of the letters in the output by the case of the 
letters in the SDML file. If you put a lowercase letter in the SDML file, it 
remains lowercase in the output. In rare cases, an argument to a tag is forced 
into upper- or lowercase by the action of the tag. If you want to avoid this 
case conversion, you can force letters into the output (in the stated case) by 
using either the <UPPERCASE> or <LOWERCASE> tags. 





Providing Quotation Marks 
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Many keyboards provide a key for a quotation mark, sometimes called 
a double-quote, that produces an effect such as shown in the following 
example: 


"Hello, sailor!" 


The quotation marks used by typesetters, on the other hand, produce an 
effect such as the following: 


“Hello, sailor!” 


In software documentation, you might want the programmer’s double-quote 
character ("). Occasionally, you will also want to surround something with 
the typesetter’s quotation marks (“ ”). 


When you want the typesetter’s quotation marks around a string, pass the 
quoted string as an argument to the <QUOTE> tag. FOE example, to obtain 
“Hello, sailor!” you must specify the following: 


<QUOTE>(Hello, sailor!) 


Include ending punctuation as part of the argument to the <QUOTE> tag if 
you want it to appear inside the quotation marks. 


VAX DOCUMENT outputs one of the typesetter’s quotation marks (the ” ) 
when it finds the ASCII double-quote character (") in a proportionally spaced 
part of your SDML file. However, in an example, where monospaced text is 
the default, the ASCII double-quote character is output as ("). 


If you need to show the ASCII double-quote character in text as it normally 
appears in a listing or on the screen (as "), code it with the <DOUBLE_ 
QUOTE> tag. Suppose you want to show the following: 


in the expression NAME := "Smith", 
You must code this text as follows: 
..in the expression NAME := <DOUBLE_QUOTE>Smith<DOUBLE_QUOTE>,... 


Similarly, the text output for a single-quote character (ASCII 39) is the 
apostrophe (’), so if you need to show the ASCII single-quote character in 
text as it normally appears in a listing or on the screen (as '), code it with the 
<SINGLE_QUOTE> tag. Suppose you want to show the following: 


in the expression NAME := 'Smith', 
You must code this text as follows: 


..in the expression NAME := <SINGLE_QUOTE>Smith<SINGLE_QUOTE>,... 
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This might appear complicated, but you often achieve what you want with 
minimum effort. The rules are as follows: 


1 In examples, where you are illustrating what appears on the screen, use 
single- or double-quote characters. Just press the keyboard’s single- or 
double-quote key. Because it is within an example, the key results in 
the screen’s single- or double-quote character (’ or ") rather than the 
apostrophe or the typesetter’s quotation mark. 


2 In text, when you want the apostrophe, press the keyboard’s single-quote 
key. Because it is within text, it prints as an apostrophe. 


3 In text, when you need to cite text from another source or cite an excerpt 
of a speech, use the <QUOTE> tag, to obtain the typesetter’s quotation 
marks. 


4 You will rarely want to show the screen or listing version of the single- 
quote key (’) or the double-quote key (") in text. However, when 
necessary, use the <SINGLE_QUOTE> and <DOUBLE_QUOTE> tags. 


The output device must have a character font that displays these typesetter’s 
characters. 





8.7 Placing Parentheses Around a Single Character 


When you enclose something in parentheses in your text, the opening and 
closing parentheses snug up against the enclosed text. However, if you are 
enclosing a single character, especially a punctuation character, the close 
placement of the parentheses overwhelms the character, for example (,). “If 
you anticipate this possible problem and place a space on either side of the 
character, (, ), you run the risk that a line break will occur at one of the 
spaces, leaving some of the parenthesized character at the end of one line and 
the rest at the start of the next line. 


Instead, you can pass the character as an argument to the <PARENDCHAR> 
tag, which will supply the parentheses and some extra space around the 
character, for example, (,). The argument to <PARENDCHAR> need not be 
limited to one character, but if the characters being parenthesized are letters 
or digits the <PARENDCHAR> tag may be unnecessary. 


The output device must have a character font that displays these 
proportionally spaced characters. 





8.8 Drawing Horizontal and Vertical Ellipses 


Writers sometimes use ellipses to emphasize the omission of text. It is not 
possible to achieve proper spacing of the ellipses by simply supplying three 
periods, because periods snug up against the preceding character. If you 
insert space characters between them, you run the risk that a line break will 
occur between them. Accordingly, use the <HELLIPSIS> tag to supply a 
horizontal ellipsis ( ... ). 


To create a vertical ellipsis, use the <ELLIPSIS> tag. 
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8.9 Showing Special Characters 


VAX DOCUMENT provides facilities for including special characters in the 
text. Among the special characters supported are the following: 


¢ Mathematical special symbols, such as operators and the uppercase Greek 
letters 


¢ Multinational Character Set (MCS), which includes such symbols as the 
British pound, the Japanese yen, umlauts, and so forth 


¢ Opening double brackets and closing double brackets 


The <MATH_CHAR> tag allows you to specify a wide range of mathematical 
symbols. The <McCS> tag offers the full range of symbols in the DIGITAL 
Multinational Character Set. The <SPECIAL_CHAR> tag supports a series of 
keywords that identifies such special symbols as the trademark symbol, the 
dagger, and the opening double bracket and closing double bracket. 





8.10 Using Formatting Tags 


The following tags provide special formatting: 


: <PAGE> 
. <LINE> 
° <KEEP > 


° <FINAL_CLEANUP> 


Be aware when using these tags that your output can vary between devices. 
If you were to use these tags in a file processed for an LNO1 printer, your 
output could look much different than you planned if you were to reprocess 
your file for a POSTSCRIPT device. Adding or deleting text can also affect the 
output when these tags are used. 


8.10.1 Specifying Page Breaks 


Use the <PAGE> tag whenever you need to force the text to begin on a 
new page of output. You can optionally direct whether the text continuation 
should begin on the next even- or odd-numbered page. 


8.10.2 Specifying Line Breaks 


Use the <LINE> tag whenever you must force text to begin on a new line 
of output. It is possible to include arguments that determine the amount of 
space before the next line or whether the text should be indented. 


In addition, the <CENTER_LINE> tag identifies a line of text that is to be 
centered within the current text margins. Its arguments also permit you to 
specify the amount of space introduced prior to outputting the line. 


The <RIGHT_LINE> tag right-adjusts a line of text within the current text 
margins. Optionally, you can specify that a large or small amount of space is 
desired. 
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8.10.3 Keeping Text on a Single Line 


The <KEEP> tag allows you to specify text that must be forced to occur on 
a particular line of output and, therefore, must not be either hyphenated 
or broken at an existing hyphen. For example, this is important whenever 
it is undesirable to break a hyphenated word, such as a product name 

like PDP-11 or when a widow or orphan might be created by automatic 
hyphenation. 


Note that when you use the <KEEP> tag in combination with the 
<HYPHENATE> tag, the hyphenation does not occur; that is, the <KEEP> 
tag overrides the normal effects of the <HYPHENATE> . 


8.10.4 Controlling Page and Line Breaks for Final Production 


The <FINAL_CLEANUP> tag is useful for performing specialized adjustments 
of line or page breaks during final production, when the use of a particular 
output device or some other consideration indicates that the normal page or 
line break should be overridden. 
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Doctype-Independent Tag Descriptions 


This chapter includes descriptions of all doctype-independent (globally used) 
tags. The tags are listed alphabetically. 


<ABSTRACT> 


<ABSTRACT> 


Begins a summary description of a document on the title page or part page 
of a document. 





FORMAT <ABSTRACT> [(title)] 





ARGUMENTS title 


Specifies a title for the abstract. 





related tags e — <FRONT_MATTER> 
e  <TITLE_PAGE> 


e <PART_PAGE> 





restrictions Can be used only in the context of a <TITLE_PAGE> or <PART_PAGE> tag. 
required <ENDABSTRACT> 
terminator 





DESCRIPTION The <ABSTRACT> tag begins a summary description of a document on the 
title page or part page of a document. 





EXAMPLES See the examples in the discussion of the <PART_PAGE> tag. 


<ACCENT> 


<ACCENT> 


Supplies a freestanding accent mark. 





FORMAT <ACCENT> (accent-mark) 





ARGUMENTS _ accent-mark 


Specifies one of the following keywords to indicated the accent mark: 











° UMLAUT 

e ACUTE 

°¢ GRAVE 
related tags °  <Mcs> 
restrictions Invalid in math. 
required None. 


terminator 





DESCRIPTION The <AccENT> tag supplies a freestanding accent mark in the printed 
output. 





EXAMPLE 


<P>Accents used in the DEC Multinational Character Set include the 
following: 

<LIST> (UNNUMBERED) 

<LE>Grave accents <PARENDCHAR> (<ACCENT> (GRAVE) ) 

<LE>Acute accents <PARENDCHAR> (<ACCENT> (ACUTE) ) 

<LE>Umlauts <PARENDCHAR> (<ACCENT> (UMLAUT) ) 

<ELS> 


This example may produce the following output: 

Accents used in the DEC Multinational Character Set include the following: 
°¢ Grave accents (*) 

° Acute accents (‘) 


e Unmlauts (") 


P 
w 


<ALIGN_AFTER> 


<ALIGN_AFTER> 


Allows you to position formatted text in a list. 





FORMAT <ALIGN_AFTER> (text) 





ARGUMENTS text 


Specifies the string under which you want to align a stack of text. 





related tags ° — <LINE> [(INDENT)] 
¢  <LIST> (STACKED) 


bd <ALIGN_NUMBER> 








restrictions Invalid in math. 
required None. 
terminator 





DESCRIPTION The <ALIGN_AFTER> tag enables you to position text in a list after the text 
specified in the argument. 





EXAMPLE 


<LIST> (STACKED\BRACES) 
<LE><ALIGN_AFTER> (UN) NUMBERED 
<LE>UNNUMBERED 

<ELS> 


This example shows how to create a stacked list where the text is aligned 
after the the string “UN.” This example may produce the following output: 
{ NUMBERED \ 

UNNUMBERED 


<ALIGN_CHAR> 


<ALIGN_CHAR> 


Identifies a nonprinting character to be used to align numeric information 
within a column of a list or table. 





FORMAT 


<ALIGN_CHAR> (character [ \ DELTA]) 





ARGUMENTS 


related tags 


restrictions 


required 
terminator 


character 
Specifies the character to be used for alignment. 


The character must be one of the following special characters: 


{ $f * # $ 
% * ~ @ 
(a a ore 


DELTA 


Specifies the character indicated for alignment is replaced on output with a 
delta character to indicate spacing. 





® <ALIGN_AFTER> 
7 <TABLE_ROW > 


ad <ALIGN—NUMBER> 





Invalid in math. 


Invalid in monospaced examples. Aligned characters might be referenced in 
an example, but the <ALIGN_CHAR> and <ENDALIGN_CHAR> tags must 
occur outside the example. 





<ENDALIGN—_CHAR> 


DESCRIPTION 


The <ALIGN_CHAR> tag identifies the character that is to be used to signify 
a space in a table row. The tag translator replaces each occurrence of the 
character with a space. The space is the same width as the numeric characters 
in the font that is active. (All numeric characters of a font have a uniform 
width.) 


Items in a column are aligned on the left by default. You may want to display 
a column of numbers aligned on the right. You can use the <ALIGN_CHAR> 
tag to define “#,” for example, as the alignment character. You make all 

the numeric entries of equal length by prefixing the shorter entries with the 
alignment character. Because the numeric characters are of uniform width, 
they will then align on the right. You can also use the alignment character to 


m 


g-— 


o 


<ALIGN_CHAR> 


add space within the number. For example, you could separate the digits of a 
number at the thousands position. 





EXAMPLES 


<ALIGN_CHAR> (#) 

<TABLE> 

<TABLE_SETUP>(2\16) 

<TABLE_ROW> (0#123#456#781\01234567 . 89) 
<TABLE_ROW> (#######35#279 \#HHHHHHG . 0) 
<TABLE_ROW> (########4#34 1\####1429 857) 
<ENDTABLE> 

<ENDALIGN_CHAR> 


This example defines the number sign as the alignment character. The 
number sign is then used to align the columns in a two-column list. This 
example may produce the following output: 


0 123 456 789 01234567.89 
35 279 6.0 
4 361 1429.857 


<TABLE> 

<TABLE_SETUP> (2\16) 

<TABLE_ROW> (0123456789\ 01234567 . 89) 
<TABLE_ROW> (35279\6.0) 

<TABLE_ROW> (4361\1429. 857) 
<ENDTABLE> 


This example shows the two-column list used in the previous example 
without the use of an alignment character. This example may produce the 
following output: 


0123456789 01234567.89 
35279 6.0 
4361 1429.857 


<P>The sum may be padded on the left with blanks, resulting in 
<ALIGN_CHAR> (#) 

<KEEP> (' ###7 .56') 

<ENDALIGN_CHAR> 


This example shows how blank output characters can be represented using 
the <ALIGN_CHAR> tag. This example may produce the output: 


The sum may be padded on the left with blanks, resulting in ' 7.56’ 


<P>The sum may be padded on the left with blanks, resulting in 
<ALIGN_CHAR> (#\DELTA) 

<KEEP> (' ###7 .56') 

<ENDALIGN_CHAR> 


This example shows how delta output characters can be represented using the 
<ALIGN_CHAR> tag. This example may produce the output: 


The sum may be padded on the left with delta characters, resulting in 
‘AMA7.56' 


<ALIGN_NUMBER> 


<ALIGN_NUMBER> 


Specifies a numeric value with alignment characters. 





FORMAT 


<ALIGN_NUMBER> (number) 





ARGUMENTS 


related tags 


restrictions 


required 
terminator 


number 

Specifies a number, which can include commas and decimal points, that is to 
be aligned with other numbers in the same column. Fields in the number that 
are to be left blank may contain pound sign (#) characters representing blank 
numbers or semicolon (;) characters representing commas or decimal points. 





bg <ALIGN—AFTER> 
° <ALIGN_CHAR> 


s <TABLE_ROW > 





Invalid in math. 





None. 





DESCRIPTION The <ALIGNNUMBER> tag lets you align columns of numbers in a table, 


when the numbers you need to enter have suppressed leading or trailing 
fields. You enter the number using the pound-sign and semicolon characters 
to represent fields in the number that are to be blank on output. 


Items in a column are aligned on the left by default. You may want to 
display a column of numbers aligned on the right, or aligned around the 
decimal point. To do this, you use the <ALIGN_NUMBER> tag to tag each 
number. 





EXAMPLES 


<table> 


<table_setup>(2\8) 


<table_row>(one\<align_number> (100,000,000. ##) ) 
<table_row>(one\<align_number> (###; ###;240.40) ) 
<table_row>(one\<align_number> (### ; ### ; ###.60) ) 
<table_row>(one\<align_number> (###; 230,425) ) 


<endtable> 


<ALIGN_NUMBER> 
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This example shows a series of numbers aligned at the decimal point. This 
example may produce the output: 


one 100,000,000. 
one 240.40 
one .60 
one 230,425 


<table> 

<table_setup>(3\15\10) 

<table_heads>(Item\Net Revenue\Percentage) 

<table_row>(Fish knives\<align_number> (#; #20; 435; ##) \<align_number>(%#10. 44) ) 
<table_row>(Clam cleaners\<align_number> (1,432,064 .23) \<align_number> (/%#45 . O#) ) 
<table_row>(Shrimp peelers\<align_number> (#; ###; 245; ##) \<align_number> (/###.86)) 
<endtable> 


This table may produce the output: 


Item Net Revenue Percentage 
Fish knives 20,435 % 10.44 
Clam cleaners 1,432,064.23 % 45.0 
Shrimp peelers 245 % .86 


<AMPERSAND> 


<AMPERSAND> 


Supplies an ampersand within an argument to a tag or in math. 





FORMAT <AMPERSAND> 





ARGUMENTS = None. 











related tags _ © The following tags label other characters that must be tagged when they 
occur in an argument to a global tag: 
<BACKSLASH> 
<CPAREN> 
<OPAREN> 
<VBAR> 
restrictions Can only be used within an argument to a tag. 
required None. 
terminator 





DESCRIPTION Use the <AMPERSAND> tag to output an ampersand within an argument to 
a tag. Outside of an argument to an SDML tag, use the regular ampersand 
character rather than the tag. 


The ampersand has a special meaning to the tag translator when it occurs 
within an argument to a tag. If you use a literal ampersand within an 
argument, it may be misinterpreted, and may cause an error in your output. 
Use the <AMPERSAND> tag to avoid any misinterpretation. 





EXAMPLE 


<SUBHEAD1>(Continuing the Line with <AMPERSAND> ) 
<P>Your BASIC statement may be formatted over two or more lines 
by terminating all lines but the last with an ampersand (&). 


This example can produce the following output. 


Continuing the Line with & 


Your BASIC statement may be formatted over two or more lines by 
terminating all lines but the last with an ampersand (&). 


g-— 


© 


<APPENDIX> 


<APPENDIX> 


Begins an appendix. 





FORMAT 


<APPENDIX> (appendix-title[ \ symbol-name]) 





ARGUMENTS 


related tags 


appendix-title 
Specifies the title for the appendix. 


symbol-name 
Specifies the symbol-name to be used in all cross-references to this appendix. 


The value of the symbol in the cross-reference file is the number assigned to 
the appendix. If the appendix is an element in a book, the appendix number 
is determined based on the position of the appendix with respect to other 
appendixes in the book. 


If the file being processed is not currently part of a book, the first appendix 
in the source file will be lettered A, and additional appendixes will be 
sequentially lettered thereafter. 


If the file containing this tag is to be included in a bookbuild, the symbol- 
name is required. 





® <SET_APPENDIX_LETTER> 











restrictions None. 

required <ENDAPPENDIX> 

terminator 

DESCRIPTION The <APPENDIX> tag starts the appendix section of a book and can contain 


9-10 


any number of other tags. Appendixes contain supplementary material at the 
end of a book. 


<BACKSLASH > 


<BACKSLASH > 


Supplies a backslash within an argument to a tag. 





FORMAT <BACKSLASH> 





ARGUMENTS = None. 











related tags e The following tags label other characters that must be tagged when they 
occur in an argument to a global tag: 
<AMPERSAND> 
<CPAREN> 
<OPAREN> 
<VBAR> 
restrictions Can be used only within an argument to a tag. 
required None. 
terminator 





DESCRIPTION Use the <BACKSLASH> tag to output a backslash within an argument to a tag. 
Outside of an argument to an SDML tag use the regular backslash character 
rather than the tag. 


Because the literal backslash character is used to separate the arguments in 
the argument list, you must use the <BACKSLASH> tag to include a backslash 
as part of your argument. 





EXAMPLE 


<SUBHEAD1>(Using the Backslash (<BACKSLASH>) ) 
<P>Use the backslash character (\) to separate BASIC statements 
on the same line. 


This example may produce the following output: 


Using the Backslash (\) 


Use the backslash character (\) to separate BASIC statements on the same 
line. 


As shown in this example, a simple backslash character is used in ordinary 
text. When a literal backslash is used in the argument to the <SUBHEAD1> 
tag, the text following the backslash is not output. 


<BOX> 


<BOX> 


Produces a box that surrounds a user-specified character string. 





FORMAT <BOX> (label) 





ARGUMENTS _/abel 


Specifies the character string to be surrounded by the box. 





related tags None. 





restrictions Valid in any context except math. 


The character string must be 15 characters or fewer. The box format might 
not be available for all output devices. 





required None. 
terminator 





DESCRIPTION The <sox> tag produces a box that surrounds a user-specified character 
string in the printed output. 





EXAMPLE 


<P>In EDT, the <BOX>(GOLD) key 
changes the function of the other keys on the keypad. 


This example produces the following output: 


In EDT, the key changes the function of the other keys on the keypad. 
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<CALLOUT > 


<CALLOUT > 


Labels a callout in an example. The <CALLOUT> tag is identical to the 
<CO> tag. 





FORMAT <CALLOUT> [(number)] 





ARGUMENTS number 


Specifies the number to be used as the callout. If not specified, the next 
number in the callout sequence is output. 





related tags e = <CALLOUTS> 
@ = <CALLOUT_REF> 


e <co> 
e = <LIST> (CALLOUT) 








restrictions None. 
required None. 
terminator 





DESCRIPTION The <CALLOUT> tag identifies a number that will be printed as a white 
letter in a black box in an example. It is used within the <CALLOUTS> and 
<ENDCALLOUTS> tags. 





EXAMPLES See the examples in the discussion of the <CALLOUTS> tag. 
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<CALLOUT_REF> 


<CALLOUT_REF> 


Labels a reference to a callout in text. 





FORMAT <CALLOUT_REF > (callout number) 


ARGUMENTS callout number 


Specifies the number to be included in the callout. 








related tags ¢ — <CALLOUTS> 
® = <CALLOUT> 


e <CO> 
¢ The following tags label other types of references: 


<REFERENCE> (symbol) 
<GREF> (reference text) 





restrictions Invalid in the context of math. 


Cannot be used in examples. 





required None. 
terminator 


DESCRIPTION The <cCALLOUT_REF> tag identifies a reference in text to a callout number 
created by the <CALLOUT> tag in an example or figure. 





EXAMPLE 


<P>In <REFERENCE>(page_transitions_fig) , 

callout <CALLOUT_REF>(1) 

labels the beginning of the process. The initial conditions are the same 
as in the previous figure and the copy-on-reference bit is set. 


This example may produce the following output: 


In Figure 3-3, callout @ labels the beginning of the process. The initial 
conditions are the same as in the previous figure and the copy-on-reference 
bit is set. 


To) 
un 
Bb 


<CALLOUTS> 


<CALLOUTS> 


Labels the beginning of a series of callouts contained in an example and 
enables the use of the <CALLOUT> and <CO> tags. (<CALLOUT> and 
<CO> are identical in their use.) 





FORMAT <CALLOUTS> [([callout-number] \ [PREFIX]})] 





ARGUMENTS _callout-number 


Sets the number with which to begin numbering the callouts. If no number is 
specified, the numbering begins with one. 


PREFIX 


Determines that the callouts will appear before the line they label, rather than 
at the end of the line. All callouts in any one example must precede the line 
they label or appear inside or at the end of the line they label. Location of 
the callouts cannot be mixed. 





related tags ° = <CALLOUT> 


<CO> 


<CALLOUT_REF> 
<LIST> (CALLOUT) 





restrictions The <CALLOUTS> and <ENDCALLOUTS> tags must surround the examples 


within which the callouts are used. 


The PREFIX argument, if specified, must be the second argument. The first 
argument can be null. For example, <CALLOUTS> (\PREFIX) is valid. 





required <ENDCALLOUTS> 
terminator | 





EXAMPLES 


<CALLOUTS> 
<CODE_EXAMPLE> 
DO WHILE (“EOF); <CALLOUT> 

READ FILECINFILE) INTOCY); 
PUT LIST(Y); <CALLOUT> 
END; 

<ENDCODE_EXAMPLE> 

<ENDCALLOUTS> 

<LIST> (CALLOUT) 

<LE>This is a <KEYWORD>(DO) statement. 

<LE>This <KEYWORD>(PUT) statement outputs the line read. 

<ENDLIST> 


<CALLOUTS> 


¥] — <CALLOUTS> (3\PREFIX) 
<CODE_EXAMPLE> 


This example may produce the following output: 
DO WHILE (EOF); @ 
READ FILE(INFILE) INTO(Y) ; 
PUT LIST(Y) ; 
END; 
@ This is a DO statement. 


@ This PUT statement outputs the line read. 


<CALLOUT> DO WHILE (“EOF); 


READ FILE(INFILE) INTOCY); 


<CALLOUT> PUT LIST(Y) ; 


<ENDCODE_EXAMPLE> 
<ENDCALLOUTS> 


3 <CALLOUTS> 
<CODE_EXAMPLE> 
DO 


<ENDCODE_EXAMPLE> 
<ENDCALLOUTS> 
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END; 


This example shows how you can set the number from which to begin 
numbering the callout sequence and how you can cause the callouts to 
precede the line to which they belong by using the argument PREFIX. This 
example may produce the following output: 


3] DO WHILE (*EOF); 

READ FILE(INFILE) INTO(Y); 
4) PUT LIST(Y); 

END; 


WHILE <CALLOUT>(9) (EOF); 
READ FILECINFILE) INTOCY); 
PUT <CALLOUT>(12) LISTCY): 
END; 


This example shows how you can place callouts inside of lines and how you 
can use an argument to the <CALLOUT> tag to control the number of the 
callout. This example may produce the following output: 


DO WHILE © (EOF); 
READ FILE(INFILE) INTOCY); 
put @ Listy); 
END; 


<CENTER_LINE> 


<CENTER_LINE> 


Specifies a line of text that is to be centered within the current margin. 





FORMAT <CENTER_LINE> (text [ \ { BIGSKIP. | 





ARGUMENTS text 
Specifies a line of text to be centered. 
BIGSKIP 
SMALLSKIP 


Specifies a set amount of vertical space to precede the element identified as a 
line or block of text. The actual amount of space created is determined by the 
document’s design. 





related tags © <LINE> 
ba <RIGHT_LINE> 





restrictions Invalid in monospaced examples, in math, and in arguments to tags that 
provide title or heading text. 


Centered text must fit within the current text margin. If you specify text that 
is too wide, the text formatter issues a warning message, and you should 
examine your output. 





DESCRIPTION The <CENTER_LINE> tag specifies a line of text that is to be centered within 
the current margin. 





EXAMPLE 


<P>Please include the following information: 

<CENTER_LINE>(Name\smallskip) 

<CENTER_LINE> (Address) 

<CENTER_LINE>(Phone Number) 
This example may produce output like the following: 
Please include the following information: 


Name 


Address 
~ Phone Number 


<CHAPTER> 


<CHAPTER> 


Begins a chapter. 





FORMAT 


<CHAPTER> (chapter-title [ \ symbol-name]) 





ARGUMENTS 


related tags 


restrictions 


required 
terminator 


chapter-title “. 
Specifies the name of the chapter. The book design may also use this 
argument in the running title. 


symbol-name 
Specifies the symbol-name to be used in all cross-references to this chapter. 


The XREF file entry for the chapter will consist of the following: 


e The value of the symbol is the number assigned to the chapter. If the 
chapter is an element in a book, the chapter number is determined based 
on the position of the chapter with respect to other chapters in the book. 


If the file being processed is not currently part of a book, the first chapter 
in the source file will be numbered 1, and additional chapters will be 
sequentially numbered thereafter. 


Symbol-names must not exceed 31 characters, and must only contain 
alphabetic letters, numbers, or underscores. Do not begin a symbol-name 
with an underscore. 





e <REFERENCE> 





Invalid within <FRONT_MATTER> and <ENDFRONT_MATTER> . 


If the file containing this tag is to be included in a bookbuild, the symbol- 
name is required. 





None. 





DESCRIPTION The <CHAPTER> tag labels the beginning of a chapter. When printed, the 


chapter title and number is printed in a larger font type. VAX DOCUMENT 
automatically increments chapter numbers. 





EXAMPLE 
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To see an example of the output that a <CHAPTER> tag produces, refer to 
the beginning of this chapter. 


<CHEAD> 


<CHEAD> 


Marks an unnumbered centered heading. Similar to the <CENTER_LINE> 
tag. 





FORMAT <CHEAD> (heading-text) 





ARGUMENTS heading-text 


Specifies the text of the subsidiary heading. 











related tags ° = <CENTER> 
e¢ <HEAD1> through <HEAD6> 
° <SUBHEAD1> 
: <SUBHEAD2> 

restrictions None. 

required None. 


terminator 





DESCRIPTION The <cHEAD> tag labels an unnumbered subsidiary heading. 


Subheadings are not numbered and do not appear in the table of contents. 
They cannot be readily used for cross-references and should be used only 
when the clarity of your exposition absolutely requires such a fine level of 
distinction. 





EXAMPLE 


<CHEAD>(How to Use the <TAG>(chead) Tag) 
<P>The use of centered headings should be restricted to occasions when the 
clarity of your exposition absolutely requires one. 


This example might produce output like the following: 


How to Use the <CHEAD> Tag 


The use of centered headings should be restricted to occasions when the 
clarity of your exposition absolutely requires one. 


i 
~ 
ito 


<CHECK_FOR_INCLUSION> 


<CHECK_FOR_INCLUSION> 


Marks a file to ensure the file is included only once in the output. 





FORMAT 


<CHECK_FOR_INCLUSION> (file-label) 





ARGUMENTS 


related tags 


restrictions 


required 
terminator 


file-label 


Specifies a string that uniquely identifies this file. This string is not the 
name of the file, rather, it simply sets an internal switch to indicate that 
the following input should be read only once. The string can contain up 
to 15 alphanumeric characters or underscores and must not begin with an 
underscore character. 





None. 





This tag is conditional, and has no relationship to the structure or content of 
the document. 





<ENDCHECK_FOR_INCLUSION > 


DESCRIPTION 


The <CHECK_FOR_INCLUSION> tag checks if the file containing the tag (the 
current input file) has been previously read. If it has, the rest of the file is 
ignored until the <ENDCHECK_FOR_INCLUSION> tag is found. If this is the 
first time that the file is being read, processing continues. 


An input file that contains this tag will not be processed from the point 
that the text processor finds this tag until the terminating tag is found. This 
can be useful for specifying the name of a definitions file that has already 
been processed for an entire book and does not need to be processed for an 
individual element of the book. 


You must use the <ENDCHECK_FOR_INCLUSION> tag at the bottom of a 
file in which the <CHECK_FOR_INCLUSION> appears. If you do not include 
the terminating tag, you might not get output after the <CHECK—FOR_— 
INCLUSION> tag, or you may receive a fatal error from the tag translator 
when it does not find the specified label. 


The position of the <CHECK_FOR_INCLUSION> tag within a file is important. 
Make sure to put the tag at the top of your file, to avoid partial processing 
of the file. Partial processing could result in illogical nesting of tags or other 
error conditions. 


<CHECK_FOR_INCLUSION> 





EXAMPLE 


<CHECK_FOR_INCLUSION> (MY_DEFS) 


<ENDCHECK_FOR_INCLUSION> 


This example shows how the <CHECK_FOR_INCLUSION> tag can be used to 
exclude a file (in this example, the file “MY_DEFS”) from processing during 
a bookbuild. This can be useful if the file specified contains tag definitions 
that are defined within each file as well as in the local definition file. To 
force the tag translator to process the definitions twice would be a waste of 
processing time. Instead, it is better to identify the definitions file with this 


tag and exclude the file from processing. 
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<CO> 


<CO> 


Labels a callout in an example. The <CO> tag is identical to the 
<CALLOUT> tag. 





FORMAT 


<CO> [(number)] 





ARGUMENTS 


related tags 


restrictions 


required 
terminator 


number 
Specifies the number to be used as the callout. 





e¢ = <CALLOUT> 
¢ = <CALLOUTS> 
¢  <LIST> (CALLOUT) 





None. 





None. 





DESCRIPTION The <co> tag identifies a number in an example and is used within the 


<CALLOUTS> and <ENDCALLOUTS> tags. 





EXAMPLES 
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See the examples in the discussion of the <CALLOUTS> tag. 


<CODE_EXAMPLE> 


<CODE_EXAMPLE> 


Begins an example of code. Code consists of words or lines of 
instructions written in a programming language or a command language. 








FORMAT <CODE_—EXAMPLE> (code) 
or 
[KEEP] 
<CODE_EXAMPLE> /( [WIDE| \ MAXIMUMI] }] 
code_example text 
<ENDCODE_EXAMPLE> 
ARGUMENTS code 


Specifies a code fragment you want to insert into your text. 


If this argument is not specified, the terminator <ENDCODE_EXAMPLE> is 
required. 


KEEP 


Specifies that the example is not to be broken across pages, that is, if the 
example does not fit on the current page, it will be placed on the next page. 
If the example itself does not fit on a single page of output, it will be broken 
anyway. 


WIDE 


Specifies that the width of the example exceeds the document's default width 
for text. Depending on the document type, this argument can be interpreted 
as follows: 


e If the document style contains a left margin area that is normally used for 
headings, the example’s width will span that area as well as the normal 
text area. 


e If the document uses a multicolumn format, the example suspends the 
multicolumn output while the example is processed. The example will be 
output and multicolumn output is then restored. 


e If the document style provides a range of sizes and styles for examples, 
this argument may be interpreted to mean that a specific size should be 
used for the example. 
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<CODE_EXAMPLE> 


related tags 


restrictions 


required 
terminator 


MAXIMUM 


Can be used in conjunction with WIDE to indicate that the example may 
require additional adjustment to fit within the bounds of the text page. 
This argument must be used with discretion, and may not be suitable in all 
document styles. 





e <INTERACTIVE> 


° <VALID_BREAK> 





Indexing tags (<x> and <Y> tags) are not permitted within code examples. 


Tab characters cannot be used to format code examples. You must use spaces 
rather than tabs. 


Do not use text element tags within a code_example (for example, <P>, 
<LIST> , or <NOTE> .) 





<ENDCODE_EXAMPLE> —Required if the code example is not passed as an 
argument. 


DESCRIPTION 
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The code that is begun with a <CODE_EXAMPLE> tag is distinguished 
typographically in the output. The size of the example, whether it will be 
indented, and how much it will be indented from the current left margin of 
text is controlled by the document design. 


There are two types of code examples. The first is a short fragment that 
you want run in with the surrounding text. The second is one or more lines 
that you want broken out of the text that surrounds it (whether or not it is 
a “formal” example with its own number, caption, and entry in the table of 
contents). 


In the first instance, where you want the example run in with the surrounding 
text, you pass the code as an argument to the <CODE_EXAMPLE> tag. In this 
instance, you do not need a terminating tag. 


In the second instance, you should enter the code between the 
<CODE_EXAMPLE> and <ENDCODE_EXAMPLE> tags. In this context, the 
character spaces and blank lines you enter to format the code will be retained. 
Also, within this context you can use the <ELLIPSIS> tag to achieve a vertical 
ellipsis showing that you have omitted some lines of code. If your code 
example is longer than a few lines, use the <VALID_BREAK> tag to indicate 
the acceptable points for a page break. 


<CODE_EXAMPLE> 





EXAMPLES 


<P>The <CODE_EXAMPLE>(WHILE INLOOP) statement causes the 
following block to be repeated until the <VARIABLE>C(INLOOP) variable 
is set to FALSE. 


This example illustrates the case of a short code example that is run in with 
the surrounding text. (One other related tag is also used.) The example may 
produce the following output: 


The WHILE INLOOP statement causes the following block to be repeated until 
the INLOOP variable is set to FALSE. 


<P>The call frame is built on the stack by the following four instructions: 
<CODE_EXAMPLE> : 
PUSHAB B°SRVEXIT 


PUSHL FP 
PUSHL AP 
CLRQ - (SP) 


<ENDCODE_EXAMPLE> 


This example illustrates the use of the <CODE_EXAMPLE> tag with a longer 
example that is broken out of the surrounding text. This example may 
produce the following output: 


The call frame is built on the stack by the following four instructions: 


PUSHAB B°SRVEXIT 


PUSHL FP 
PUSHL AP 
CLRQ - (SP) 
3 <P>The instruction sequence listed here (patterned after code in 


module PROCSTRT) shows this second technique. 
<CODE_EXAMPLE> 


PUSHL executive-mode-PSL 
BSBB DOREI 

<ELLIPSIS> 

PUSHL user-mode-PSL 

BSBB DOREI 

<ELLIPSIS> 

DOREI: REI 


<ENDCODE_EXAMPLE> 


This example shows a longer code example that uses the <ELLIPSIS> tag as 
well. This example may produce the following output: 


The instruction sequence listed here (patterned after code in module 
PROCSTRT) shows this second technique. 


PUSHL executive-mode-PSL 
BSBB DOREI 


PUSHL user-mode-PSL 
BSBB DOREI 


DOREI : REI 
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<COMMENT> 


<COMMENT> 


Marks a portion of your SDML input file that you do not want to appear 
in your output. Text marked by a <COMMENT> tag is ignored by the tag 
translator during processing. 





FORMAT <COMMENT> (comment-text) 
or 
<COMMENT> 
comment-text 


<ENDCOMMENT> 





ARGUMENTS text 


Specifies the text you do not want to appear in your output. 











related tags None. 

restrictions You cannot nest <COMMENT> and <ENDCOMMENT> tags. 

required <ENDCOMMENT> — Required if the text is not passed as an argument. 
terminator 





DESCRIPTION Comments can provide useful reminders for your own use or use by writers 
who may modify your SDML file in the future. Comments can also be used 
to exclude portions of text from the output file, but that you might wish to 
save for later inclusion. The text remains in the SDML file, but does not 
appear in the output. 


<COMMENT> 





EXAMPLE 


<CODE_EXAMPLE> 


000000 
000002 
000004 
000006 
000010 


’ 


; SECONDARY POOL COMMAND BUFFER BLOCKS 


.=0 
C.CLK: 


C.CTCB: 
C.CUCB: 


C.CCT: 


C.CSTS: 


<COMMENT> 


000012 
000012 


C.CMCD: 


C.CSO: 


<ENDCOMMENT> 


000014 
000015 


000016 C.CTXT: 
<ENDCODE_EXAMPLE> 


C.CTR: 
C.BLK: 


. BLKW 
. BLKW 
. BLKW 
. BLKW 
. BLKW 


. BLKW 


. BLKW 
. BLKW 


ee 


;LINK WORD 


;TCB ADDRESS OF TASK TO RECEIVE COMMAND 
;UCB ADDRESS IF RESPONSIBLE TERMINAL 
;CHARACTER COUNT, EXCLUDING TRAILING CR 


;STATUS MASK 


; SYSTEM MESSAGE CODE 
;STARTING OFFSET OF VALID COMMAND TEXT 


; TERMINATING CHARACTER 


;SIZE OF PACKET IN SEC POOL (32 WD.) BLOCKS 


;COMMAND TEXT, FOLLOWED BY CR 


This example shows a code example with comments embedded in the code. 
The tag translator ignores the text between the <COMMENT> tag and the 
<ENDCOMMENT> tag. This example may produce the following output: 


000000 
000002 
000004 
000006 
000010 


000014 
000015 
000016 


; SECONDARY POOL COMMAND BUFFER BLOCKS 


-=0 
CLK: 


CCT: 


.BLK: 


aan aagaaaunaA 


.CTCB: 
.CUCB: 


.CSTS: 
.CTR: 


.CTXT: 


. BLKW 
. BLKW 
. BLKW 
. BLKW 
. BLKW 


. BLKW 
. BLKW 


PPP PP 


i 


; LINK WORD 

;TCB ADDRESS OF TASK TO RECEIVE COMMAND 
;UCB ADDRESS IF RESPONSIBLE TERMINAL 
;CHARACTER COUNT, EXCLUDING TRAILING CR 
;STATUS MASK 


; TERMINATING CHARACTER 
;SIZE OF PACKET IN SEC POOL (32 WD.) BLOCKS 
;COMMAND TEXT, FOLLOWED BY CR 
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<CONDITION> 


<CONDITION> 


Marks a section of an SDML file that is not processed unless one 
of the arguments to the tag matches the argument in the related 
<SET_CONDITION> tag. : 





FORMAT <CONDITION> (condition-name [ \ condition-name] 
[ \ condition-name)]) 





ARGUMENTS — condition-name 


Specifies a condition name created with the <SET_CONDITION> tag. 





related tags ¢ = <SET_CONDITION> 





restrictions <CONDITION> tags cannot be nested. There must be a strict correspondence 
between <CONDITION> and <ENDCONDITION> tags. 


In monospaced examples, <CONDITION> and <ENDCONDITION> tags cannot 
occupy the same line as text for the example. 





required <ENDCONDITION> — Required if the text is not passed as an argument. 
terminator 


DESCRIPTION The <cONDITION> tag indicates that the following section of text should 
be processed only upon the condition that one of the tag’s arguments 
matches the argument in the related <SET.CONDITION> tag. If the two 
tags’ arguments are identical, the marked text is processed and included in 
the output file. If the arguments differ, the text is excluded from processing. 
The <ENDCONDITION> tag marks the end of the conditional text. 


This tag can be very useful if you must produce two or more documents 
that differ in minor ways but contain much of the same text. It is efficient to 
maintain one SDML file and identify the portions of text that are unique to 
each document. 


Before processing the SDML file, you can specify the condition-name for the 
desired document in the <SET_CONDITION> tag or in the /CONDITION 
qualifier in the DOCUMENT command line. When the tag translator 
processes the file, it includes all portions of text tagged with that condition- 
name argument and ignores all portions of text tagged with any other 
condition name. To obtain another version of the document, change the 
condition name in the argument to the <SET_CONDITION> tag, and reprocess 
the file. 


When you supply more than one condition-name argument to the 
<CONDITION> tag, only one of the condition names need be present for 
the conditional text to be processed. 


This is shown in the first example. 


<CONDITION> 





EXAMPLES 


<CONDITION> (Christmas) 
<P>Christmas, by convention, is celebrated on December 25th... 
<ENDCONDITION> 


<CONDITION> (Chanukah) 
<P>Chanukah is called the Festival of Lights ... 
<ENDCONDITION> 


<CONDITION>(Wash_Bday) 
<P>Washington's Birthday is on February 22nd... 
<ENDCONDITION> 


<CONDITION> (Christmas\Chanukah) 

<HEAD1>(Religious Holidays) 

<P>This paragragh contains general information about several religious 
holidays... 

<ENDCONDITION> 


This example shows how a file could be organized if you were writing about 
holidays in general, and Christmas, Chanukah, and Washington’s Birthday 
in particular. Any of three different condition states could be set at the top 
with the tag <SET_CONDITION> (Christmas), <SET_CONDITION> (Chanukah), or 
<SET_CONDITION> (Wash_Bday). The example contains four paragraphs, with 
each paragraph conditionalized differently. 


If the file is processed with <SET_CONDITION> (Christmas), the information 
on Christmas and religious holidays is processed. If the file is processed 
with <SET_CONDITION> (Chanukah), the information on Chanukah 

and religious holidays is processed. If the file is processed with 
<SET_CONDITION> (Wash_Bday), the information on Washington’s birthday 
is processed. 


The function of the <SET_CONDITION> tag can be obtained by using the 
/CONDITION qualifier on the DOCUMENT command line instead. 


<SET_CONDITION> (VMS) 


When the 

<CONDITION> (VMS) VAX/VMS<ENDCONDITION> 

<CONDITION> (RSX) RSX11M/RSX11M-PLUS<ENDCONDITION> 

command language interpreter translates the logical name... 


This example shows how one of two clauses can be omitted from processing 
based on the condition name specified in the <SET_CONDITION> tag. The | 
section of text that is identified with <CONDITION> (VMS) would be processed 
and placed in the output file, whereas the other text would be omitted. This 
example would have the following output: 


When the se cas command language interpreter translates the logical 
name . 


9-29 


<CONDITION> 


Kk) <SET_CONDITION> (RSX) 
<P>When RSX... 


<CONDITION>(VMS\RSX) 
<P>When the operating system... 


<ENDCONDITION> 
<CONDITION>(RSTS) 
<P>When RSTS .. . 


<ENDCONDITION> 


This example shows how text that is applicable to the two condition names 
“VMS” and “RSX” can be differentiated from text that is applicable to the 
condition-name “RSTS.” By supplying both the VMS and RSX arguments to 
the first <CONDITION> tag, the writer ensures that the text will be included 
in the output if either the VMS or RSX condition-name is set. (Other text in 
the same SDML file might be conditional for only one of these condition- 
names.) 


9-30 


<CONTENTS_FILE> 


<CONTENTS_FILE> 


Specifies that the table of contents output file for a document should be 
included when the document is processed. 











FORMAT <CONTENTS_FILE> [(file-spec)] 

ARGUMENTS _file-spec 
If you place the <CONTENTS_FILE> tag in an SDML file that will be included 
in another file later, you must specify the exact file name of the contents as 
the <CONTENTS_FILE> tag’s argument. 

restrictions <CONTENTS_FILE> is valid only within the context of front matter or within 


related tags 


required 
terminator 


a profile of a book. 





° <PROFILE> 





None. 





DESCRIPTION 


The <CONTENTS_FILE> tag specifies the position in a source file where a 
table of contents output file should be included. This tag does not produce 
a table of contents, but simply indicates placement of the contents file. A 
contents file is produced when the qualifier /CONTENTS is ppeciaed on the 
DOCUMENT command line. 


The profile tags <CONTENTS_FILE> and <INDEX_FILE> can be placed in 
either the profile of a book or in a source file. If you are creating a book (with 
a profile to be processed through a bookbuild), place these tags in the profile 
to be sure of correct placement in the output. 


A contents file always receives the filetype .DVI —device, where device is 
the type of output device you specified on the command line. For more 
information on contents generation, see Chapter 7. 


To create a table of contents from an individual file that contains a 
<CONTENTS_FILE> tag, specify the /CONTENTS qualifier on the command 
line. 





EXAMPLE 


To see the result of the <CONTENTS_FILE> tag, refer to the table of contents 
in this manual. The <CONTENTS_FILE> tag was placed in the profile file 
before the preface file. 


9-31 


<COPYRIGHT_DATE> 


<COPYRIGHT_DATE> 


Inserts a copyright date line on the copyright page along with other 
system-specific copyright information. 





FORMAT <COPYRIGHT_DATE> (date/ \ owner]) 





ARGUMENTS date 


Specifies official printing date information for the book. 


owner 
Specifies the owner of the copyright. Local conventions might preclude use 
of this argument. 








restrictions The <COPYRIGHT_DATE> tag is valid only within the context of a 
<COPYRIGHT_PAGE> ... <ENDCOPYRIGHT_PAGE> . 

required None. 

terminator 





DESCRIPTION The <copyRIGHT_DATE> inserts a copyright date line on the copyright page 
along with other system-specific copyright information. 





EXAMPLE 


<Copyright_page> 
<Copyright_date>(1987\Tomato Magnates, Inc.) 
<Endcopyright_page> 
This example produces a full page of output with the following text: 


Copyright ©1987 Tomato Magnates, Inc. 


fe) 


—32 


<COPYRIGHT_PAGE> 


<COPYRIGHT_PAGE> 


Begins a copyright page and enables copyright page tags. 





FORMAT <COPYRIGHT_PAGE> 





ARGUMENTS = None. 





restrictions This tag can only be used in the context of a copyright page and in the front 
matter of a book. 








required <ENDCOPYRIGHT_PAGE> 
terminator 
related tags ©  <FRONT_MATTER> 


° <PRINT_DATE> 


e <COPYRIGHT_DATE> 





DESCRIPTION The following copyright page tags that are enabled by <COPYRIGHT_PAGE> : 
| ¢ = <PRINT_DATE> 


° <COPYRIGHT_DATE> 





EXAMPLE 


<FRONT_MATTER> (front) 
<COPYRIGHT_PAGE> 
<PRINT_DATE>(March 1987) 
<COPYRIGHT_DATE> (1987) 
<ENDCOPYRIGHT_PAGE> 
<ENDFRONT_MATTER> 


This example shows the order in which the copyright page tags are 

used. Notice that you must enable the copyright page tags within the 
<FRONT_MATTER> tag. The output of this example is a separate copyright 
page, containing the print and copyright dates, in the front matter of the 
book. 


To see an example of all the front matter tags in their correct order, refer to 
the example in the <FRONT_MATTER> tag. 
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WwW 


<CP> 


<CP> 


Marks the continuation of a paragraph that has been interrupted by another 
text element. 





FORMAT <CP> 





related tags ° <P> 





ARGUMENTS = None. 





restrictions Invalid in math. 





required None. 
terminator 





DESCRIPTION The <P> and <cpP> tags may have no visible difference in effect. In a book 
design in which all new paragraphs begin flush left, the formatted results 
achieved by a <CP> tag and bya <P> tag are identical. However, ina 
book design in which paragraphs are indented, the continued paragraph may 
still begin flush left. 


In some instances, the <CP> tag will keep text that follows a list or 
monspaced example from being “widowed” at the top of the following 
page. In other words, a continued paragraph is more closely attached to the 
text element it follows. 





EXAMPLE 


<P>Each time you log in, the system automatically executes 

two types of login command procedures: 

<LIST> (UNNUMBERED ) 

<LE>A system login command procedure 

<LE>Your personal login command procedure 

<ENDLIST> 

<CP>These login procedures are described in the following sections. 


This example may produce the following output using a book design in which 
paragraphs are indented: 


Each time you log in, the system automatically executes two types of 
login command procedures: 


¢ A system login command procedure 


¢ Your personal login command procedure 


These login procedures are described in the following sections. 


<CPAREN> 


<CPAREN> 


Supplies an unmatched closing parenthesis in an argument to a tag. 





FORMAT <CPAREN> 





ARGUMENTS None. 





related tags ¢ The following tags label other characters that must be tagged when they 
occur in an argument to a global tag: 


<AMPERSAND> 
<BACKSLASH > 
<OPAREN> 
<VBAR> 








restrictions None. 
required None. 
terminator 





DESCRIPTION The <cCPAREN> tag can be used anywhere to insert a closed parenthesis 
character into text. However, it is only beneficial (in terms of keystrokes and 
control of the output) as an unmatched closing parenthesis in an argument 
passed to a tag. 


An unmatched parenthesis in an argument can cause errors when processed 
because the parentheses are used to determine the beginning and ending of 
an argument list. The <CPAREN> tag inserts the closed parenthesis character 
but is not evaluated as a closed parenthesis. 





EXAMPLE 


<SUBHEAD1>(Using a Closed Parenthesis 
<PARENDCHAR>(<CPAREN>) in an Argument to a Tag) 


This example may produce the following output: 


Using a Closed Parenthesis ()) in an Argument to a Tag 
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ol 


<DATE> 


<DATE> 


Produces the current system date or time, or the user-specified date and 
time. 





FORMAT <DATE> [( FULL yy 
: date-text 





ARGUMENTS FULL 


Produces a full VMS date and time string in the format “dd-mmm-yyyy 
hh:mm:ss.hh.” If no argument is specified, only the date may be produced 
in the format “Month day, year.” (The precise format may be modified in 
different doctypes.) 


date-text 

Text that you provide as the current date. If no argument is specified, only 
the date may be produced in the format “Month day, year.” (The precise 
format may be modified in different doctypes.) 











related tags None. 
restrictions Invalid in math. 
required None. 
terminator 





DESCRIPTION The <DATE> produces a date that is based either on the time at which the 
tag translator begins execution, or the time as specified by the user. The 
<DATE> tag produces a date in one of three forms as shown in the following 


table: 

<DATE> February 26, 1988 
<DATE> (FULL) ; 26-FEB-1988 15:46:00.29 
<DATE> (February 26th, 1988 A.D.) February 26th, 1988 A.D. 


Note that even if the <DATE> (FULL) tag is specified multiple times in a source 
file, it will always produce the same value and so cannot be used for timing 
information. 


<DATE> 





EXAMPLES 


4 <DATE> 


2 <DATE> (FULL) 


Example 1 may produce the following output: June 29, 1988 


Example 2 produces the following output: 29-JUN-1988 16:40:33.52 


<DEFINE_BOOK_NAME> 


<DEFINE_BOOK_NAME> 


Defines the title of a book and associates a user-defined symbol-name 
with that title for later reference. 





FORMAT 


<DEFINE_BOOK_NAME> (symbol-name \ title) 





ARGUMENTS 


related tags 


symbol-name 

Specifies the symbol that is associated with the title of the book. Symbol- 
names must not exceed 31 characters, and must only contain alphabetic 
letters, numbers, or underscores in them. Do not begin a symbol-name with 
an underscore. 


title 
Specifies the exact text of the book’s title. 





° <DEFINE_SYMBOL> 


° <REFERENCE> 











restrictions None. 

required None. 

terminator 

DESCRIPTION The <DEFINE_BOOK_NAME> tag specifies a book’s title and adds an 


associated user-defined symbol-name to the cross-reference file. When 
you subsequently reference this title with the <REFERENCE> tag, supplying 
the same symbol-name as an argument to <REFERENCE> , the book title is 
retrieved from the cross-reference file and is substituted for the reference. 


Depending on the document type, the title may be output with emphasized 
text (for example, italicized). 


Note that the symbol-name argument is the first argument to the tag. In text 
element tags, the symbol-name is always the second argument. Only the 
<DEFINE_BOOK_NAME> and <DEFINE_SYMBOL> tags take a symbol-name as 
a first argument. Placing the symbol-name as the first argument to these tags 
makes it easy to keep track of your symbol-names when you list them in a 
local definitions file. All of the symbol-names will be aligned and easy to find 
in the file. 


<DEFINE_BOOK_NAME> 





EXAMPLE 


<DEF INE_BOOK_NAME>(games_book\Book of Games, Volume 2) 


This example illustrates the use of the <DEFINE_BOOK_NAME> tag for 
defining the symbol-name of the book “Book of Games” as games—_book. The 
tag 9<REFERENCE> (games_book) can be used anywhere in the document to refer 
to this book name. 
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<DEFINE_SYMBOL> 


<DEFINE_SYMBOL> 


Associates a string of text with a user-defined symbol, so that the text 
can be referenced via this symbol throughout the document. 





FORMAT 


<DEFINE_SYMBOL> (symbol-name \ text-string) 





ARGUMENTS 


related tags 


restrictions 


required 
terminator 


symbol-name 

Specifies the name assigned to the symbol. All symbol-names must not 
exceed 31 characters, and must only contain alphabetic letters, numbers, or 
underscores in them. Do not begin a symbol-name with an underscore. 


text-string 

Specifies the text that will be referenced via the symbol-name. Throughout 
the document, you can specify the symbol-name in the <REFERENCE> tag, 
and this text-string will be substituted for the symbol-name during processing. 





e <DEFINE_BOOK_NAME> 
° <DELAYED> 


° <REFERENCE> 





None. 





None. 


DESCRIPTION 


Note: 


The <DEFINE_SYMBOL> tag specifies a string of text and associates the text 
with a user-defined symbol-name. It adds the symbol-name and the text to 
the symbol table. When you subsequently reference this text by using the 
<REFERENCE> tag and specifying the same symbol-name as its argument, the 
current value of the symbol-name is retrieved from the table and the text is 
substituted for the reference. 


For more information on the use of the symbol table, see Chapter 6. 


The symbol-name argument to the <DEFINE_SYMBOL> tag must be on the 
same line as the tag; spaces and carriage returns are significant and are 
interpreted as part of the symbol-name. 


Only the <DEFINE_SYMBOL> and <DEFINE_BOOK_NAME> tags use a symbol- 
name as a first argument. In text element tags, the symbol-name is often the 
second argument. Placing the symbol-name as the first argument to these 
tags makes it easy to keep track of your symbol-names when you list them in 
a local definitions file. All of the symbol-names will be aligned and easy to 
find in the file. 


<DEFINE_SYMBOL> 





EXAMPLE 


<define_symbol>(set_logical\RTL routine Set Logical Name, LIB$SET_LOGICAL, ) 


LY 


<P>The <REFERENCE>(set_logical) requests the calling process's CLI to 
define or redefine a supervisor-mode logical name. 


This example shows how a phrase, “RTL routine Set Logical Name, LIB$SET_ 
LOGICAL,” can be defined as a symbol-name, “set_logical,” and then 
referenced in text by that symbol-name. By referencing the symbol-name 

in the places you want the phrase to occur, you can save keystrokes and 
ensure that you never have a typing error in that phrase. 


The example produces the following output: 


The RTL routine Set Logical Name, LIBSSET_LOGICAL, requests the calling 
process’s CLI to define or redefine a supervisor-mode logical name. 
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<DEFINITION_LIST> 


<DEFINITION_LIST> 


Begins a definition list. 





FORMAT 


<DEFINITION_LIST> 





ARGUMENTS 


related tags 


None. 





id <DEFINITION_LIST_HEAD > 
bf <DEFLIST_ITEM > 


®  <DEFLIST_DEF> 














restrictions None. 

required <ENDDEFINITION _LIST > 

terminator 

DESCRIPTION A definition list contains paired entries, consisting of the item being defined, 
introduced by the <DEFLIST.ITEM> tag; and the item’s definition, introduced 
by the <DEFLIST.DEF> tag. The definition list differs from a list created 
with the <LIST> tag in that the definition list items are not numbered or 
called-out in any way. 
The definition list can be given a heading with the <DEFINITION_LIST_HEAD> 
tag. Each list can contain one or more items, tagged with <DEFLIST_ITEM> , 
and each item can have a definition, tagged with <DEFLIST_DEF> . 

EXAMPLE 
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<definition_list> 
<deflist_item>(Hargreaves, James) 
<deflist_def> 

d. 1778. English inventor. 
<deflist_item>(Harris, Joel Chandler) 
<deflist_def> 

1848-1908. American author. 
<deflist_item>(Harvey, William) 
<deflist_def> 

1578-1657. English physician and anatomist. 
<deflist_item>(Hauptmann, Gerhard) 
<deflist_def> 

1862-1946. German author. 
<enddefinition_list> 


<DEFINITION_LIST> 


This example may produce the following output: 


Hargreaves, James 
d. 1778. English inventor. 


Harris, Joel Chandler 
1848-1908. American author. 


Harvey, William 
1578-1657. English physician and anatomist. 


Hauptmann, Gerhard 
1862-1946. German author. 
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<DEFINITION_LIST_HEAD> 


<DEFINITION_LIST_HEAD> 


Supplies the heading to precede a definition list. Output formatting is 
controlled by the document-type. 





FORMAT <DEFINITION_LIST_HEAD> (heading-text) 





ARGUMENTS §heading-text 


Specifies the text for a heading to precede the definition list. 





related tags ¢  <DEFINITION_LIST> 
¢  <DEFLIST_ITEM> 


e <DEFLIST_DEF> 








restrictions Can be used only in the context of a <DEFINITION_LIST> tag. 
required None. 
terminator 





DESCRIPTION The <DEFINITION_LIST_.HEAD> tag adds a heading to a list of defined items 
specified by the <DEFINITION_LIST> tag. 





EXAMPLE 


<definition_list> 
<definition_list_head>(Worldwide Associates) 
<deflist_item> (IAAF) 

<deflist_def> 

International Amateur Athletic Federation. 
<deflist_item> (IAEA) 

<deflist_def> 

International Atomic Energy Agency. 
<enddefinition_list> 


This example might have the following output, depending on the document 
type specified: 





WORLDWIDE IAAF 
ASSOCI ATES International Amateur Athletic Federation. 
IAEA 


International Atomic Energy Agency. 
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<DEFLIST_DEF> 


<DEFLIST_DEF> 


Begins the text that defines an item in a definition list. 





FORMAT 


<DEFLIST_DEF> text 





ARGUMENTS 


related tags 


restrictions 


required 
terminator 


text 
Specifies the text of the definition. 





e <DEFINITION _LIST> 
® <DEFINITION _LIST_HEADS> 


. <DEFLIST_ITEM > 





Can be used only in the context of a <DEFINITION_LIST> tag. 





None. 





DESCRIPTION A definition list contains paired entries, consisting of the item being defined, 


introduced by the <DEFLIST_ITEM> tag; and the item’s definition, introduced 
by the <DEFLIST_DEF> tag. 





EXAMPLE 


See the example in the discussion of the <DEFINITION_LIST> tag. 
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<DEFLIST_ITEM> 


<DEFLIST_ITEM> 


Marks an item to be defined in a definition list. 





FORMAT <DEFLIST_ITEM> (item \ item...)) 





ARGUMENTS item 


Specifies the item to be defined. Up to seven items can be stacked. 





related tags ¢ — <DEFINITION_LIST> 
¢  <DEFINITION—LIST_HEADS> 


7 <DEFLIST_DEF > 





restrictions Can be used only in the context of a <DEFINITION_LIST> tag. 





required <DEFLIST_DEF> 
terminator 





DESCRIPTION A definition list contains paired entries, consisting of the item being defined, 
introduced by the <DEFLIST_ITEM> tag; and the item’s definition, introduced 
by the <DEFLIST_DEF> tag. 





EXAMPLE 


<definition_list> 

<deflist_item>(Hargreaves, James\d. 1778.) 
<deflist_def>English inventor. 

<deflist_item>(Harris, Joel Chandler\Born 1848.\Died 1908.) 
<deflist_def>American author. 

<enddefinition_list> 


This example may have the following output: 


Hargreaves, James 
d. 1778. 

English inventor. 

Harris, Joel Chandler 
Born 1848. 

Died 1908. 


American author. 
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<DELAYED> 


<DELAYED> 


Allows you to specify text that contains tags in an argument to another 
tag. Execution of tags is delayed until the text is output. 








FORMAT <DELAYED> (delayed-text) 
or 
<DELAYED> 
delayed-text 
<ENDDELAYED> 
ARGUMENTS delayed-text 


related tags 


The text containing tags whose execution is delayed until the text is output. 





® <DEFINE_BOOK_NAME> 


ba <DEFINE_SYMBOL> 











restrictions The <DELAYED> tag may not be nested within itself. 

required <ENDDELAYED> —Required if the delayed text is not specified as an 
terminator argument. 

DESCRIPTION You can use a tag within an argument to another tag. This is called nesting 


a tag in an outer tag’s argument. Normally, the tag translator evaluates the 
nested tag first, then evaluates the outer tag. 


When the outer tag is the <DEFINE_SYMBOL> tag, a nested tag in the text 
argument will be evaluated before the <DEFINE_SYMBOL> tag is evaluated. 
Often, this leads to an undesirable result. You would like the text argument 
of the +<DEFINE_SYMBOL> tag to be preserved as it is stated until the text is 
recalled at another place by the <REFERENCE> tag. 


The <DELAYED> tag can be used to surround the text argument of a 
<DEFINE_SYMBOL> tag. The effect of the <DELAYED> tag is to delay the 
evaluation of the tags within it until those tags are about to be output where 
the symbol has been referenced. 
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<DELAYED> 





EXAMPLE 


<define_symbol> (TEMP_CHART_EX\<delayed> 
<example>(Temperature Chart) 
<code_example> 
Centigrade 0 Fahrenheit 32 
Centigrade 100 Fahrenheit 212 
<endcode_example> 
<endexample> 
<enddelayed>) 


The symbol TEMP_CHART_EX is associated with the text string that was 
enclosed by the <DELAYED> and <ENDDELAYED> tags. None of the 
enclosed tags will have been evaluated. 


Subsequently, the symbol may be referenced by a <REFERENCE> tag as in 
the following code fragment. 


<REFERENCE> (temp_chart_ex) 
The previous code fragment may have the following output. 


Example x—x Temperature Chart 


Centigrade 0 Fahrenheit 32 
Centigrade 100 Fahrenheit 212 
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<DOCTYPE> 


<DOCTYPE> 


Specifies the document type for your file. This tag is for informational 
purposes only. 














FORMAT. <DOCTYPE> (document-type) 
ARGUMENTS document-type 

Specifies the design you want to use for your file. 
restrictions None. 
required None. 
terminator 


DESCRIPTION The <bDocTyPE> tag specifies the document type for your file. The 


designated doctype determines how the file’s formatted output will appear. 
Each doctype follows a book design as determined by the writer and editor. 


You do not have to include the <DOCTYPE> tag in your file in order to 
process your file. You can include this tag for information purposes. You 
must specify the doctype in the DOCUMENT command line. Doing so allows 
you to process your file using different doctypes to determine which one suits 
your needs without having to modify the file. 


Table 9-1 summarizes the supported doctypes and the DOCUMENT 
command keyword names to be specified in processing these doctypes. 


Table 9—1 Supported Document Types 


Document Type 


Keyword Usage 

ARTICLE Articles 

LETTER Letters or memos 

MANUAL Users’ manuals 

MILSPEC Military specifications 

OVERHEADS Overhead slides for transparencies 

REPORT General-purpose documents 

SOFTWARE User manuals containing software-specific information 


In addition, a number of the document types listed in Table 9-1 have a choice 
of designs. The design selected is specified during document processing by 
appending the design name to the document-type keyword. Table 9-2 
summarizes the key characteristics of the doctypes and their designs. 
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<DOCTYPE> 


Table 9-2 Summary of Alternate Designs for Doctypes 


Keywords Size 
ARTICLE 83 x 11 
LETTER 85 x 11 
MANUAL.GUIDE 7x9 
MANUAL.PRIMER 7x9 
MANUAL.REFERENCE 83 X11 
MILSPEC 85 X11 
OVERHEADS 83 x11 
OVERHEADS.35MM 63 Xx 53 
REPORT 85 x 11 
REPORT. TWOCOL 85 Xx 11 
SOFTWARE.BROCHURE 7x9 
SOFTWARE.GUIDE 7x9 
SOFTWARE_HANDBOOK 7x9 
SOFTWARE.POCKET_ 5yX7 
REFERENCE 

SOFTWARE.REFERENCE 85x11 


SOFTWARE.SPECIFICATION 85 x 11 


Headings' 
U 


U 
N 
U 


z2Zz 


Cc 2:2 C¢ 2 


22 


Characteristics 

Two columns for text 

Uses full page width 
Chapter-oriented; headings unruled 


Chapter-oriented with sequential page numbering; 
headings unruled 


Chapter-oriented; headings unruled 


Chapter-oriented with sequential page numbering; 
two-line running headings unruled 


Uses the full page width for text; headings are not 
ruled 


Two columns for text 

Headings set in left margin, ruled 

Headings set in left margin, ruled 

Headings set in left margin, ruled 

Headings optionally numbered or unnumbered 


Headings set in left margin, ruled 
Headings unruled; uses full page width 





'N=numbered headings, U=unnumbered headings 


Tags unique to specific document types are summarized in the VAX 
DOCUMENT User Manual, Volume 2. 





EXAMPLE 


<DOCTYPE> (report) 


This example shows how a book’s doctype can be specified as “report.” 


Refer to the document VAX DOCUMENT Design Samples for examples of the 
output of the various doctypes. 


<DOUBLE_QUOTE> 


<DOUBLE_QUOTE> 


Supplies a double quotation mark as it appears on the screen. 





FORMAT 


<DOUBLE_QUOTE> 





ARGUMENTS 


related tags 


restrictions 


required 
terminator 


None. 





° <SINGLE_QUOTE> 


° <QUOTE> 





None. 





None. 





DESCRIPTION Typesetters distinguish between opening quotation marks and closing 


quotation marks, for example, “a quoted string.” Your terminal, on the 

other hand, has two possible characters you can use for quotation marks: 

the double quote, (") (ASCII 34) and the single quote (') (ASCII 39). In 
programming languages, a quoted string is usually delimited at each end with 
the same character, either “a quoted string," or ‘a quoted siring.' 


If you use the terminal’s double quotation mark in normal text in your SDML 
file, you get the typesetter’s closing quotation mark in the output. Thus, if 
you enter “abc” in your SDML file, you will see “abc” in your printed output. 
This is usually undesirable. 


You have two choices: 


To cause your typeset output to show a double quotation mark as it is 
shown on the terminal, use the <DOUBLE_QUOTE> tag. This is your 
most likely choice for showing examples of user input or screen displays. 


To cause your typeset output to follow typesetting conventions by using 
distinct opening and closing quotation marks, use the <QUOTE> (text) 
tag. You would use this in citing a passage from another book. 


Thus, there are very few occasions in which you press the double quote 
character on your keyboard while editing an SDML file. 


<DOUBLE_QUOTE> 





EXAMPLES 


4 <P>You can cause the translation of a symbol by using a double 
quotation mark (<DOUBLE_QUOTE>) directly in front of it. 


This example shows the use of the <DOUBLE_QUOTE> tag. It may produce 
the following output: 


You can cause the translation of a symbol by using a double quotation mark 
(") directly in front of it. 


2. <P>You can cause the translation of a symbol by using a double 
quotation mark (") directly in front of it. 


This example shows what your output would be like without using the tag, 
but just entering the character from the keyboard. 


You can cause the translation of a symbol by using a double quotation mark 
(") directly in front of it. 
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<ELEMENT> 


<ELEMENT> 


Identifies a file that contains an element of a book. 





FORMAT 


<ELEMENT > (file-spec) 





ARGUMENTS 


related tags 


restrictions 


required 
terminator 


file-spec 
Specifies a file. The file type must be supplied. 





7 <PROFILE> 


e <INCLUDES_FILE> 





Must be used in the context of a profile. 





None. 


DESCRIPTION 


A profile of a book is required in order to build (process) a book. A book’s 
profile contains an ordered list of the elements that comprise the book. In 
the profile, you label each of these elements with an <ELEMENT> tag. Only 
those files listed with <ELEMENT> tags are included in the book during the 
bookbuild. They should be listed in the profile in the order in which they are 
presented in the book. 


A file specified as an element must begin with one of the following tags: 


° <APPENDIX> 


<CHAPTER> 


<FRONT MATTER> 


<GLOSSARY> 


<PART> 


For more information on creating a profile and bookbuilding, see Chapter 4. 





EXAMPLE 


Assume that a writer is writing a book that contains several chapters and that 
one of the chapters is the file My_Intro_Chap.SDML. At the top of this file is 
included the tag: <CHAPTER> (Introduction\intro_chap). 


Along with the other <ELEMENT> tags for this book, the profile for this book 
would then contain the following: 


<ELEMENT> (My—Intro_Chap.SDML) 
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<ELLIPSIS> 


<ELLIPSIS> 


Supplies vertical ellipsis points to show omitted material in text and tables. 





FORMAT 





ARGUMENTS = None. 











<ELLIPSIS> 


related tags e <HELLIPSIS> 
restrictions Invalid in math. 
required None. 
terminator 





DESCRIPTION The <EL.iPsis> tag supplies vertical ellipsis points to show omitted material 
in text and tables. The vertical ellipsis is positioned with respect to the current 
left margin. 





EXAMPLE 


<P>The instruction sequence listed here (patterned after code in 
module PROCSTRT) shows this second technique. 


<CODE_EXAMPLE> 


PUSHL executive-mode-PSL 
BSBB DOREI 

<ELLIPSIS> 

PUSHL user-mode-PSL 

BSBB DOREI 

<ELLIPSIS> 

DOREI : REI 


<ENDCODE_EXAMPLE> 


This example may produce the following output: 


The instruction sequence listed here (patterned after code in module 
PROCSTRT) shows this second technique. 


co 
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PUSHL 
BSBB 


PUSHL 
BSBB 


DOREI: 


executive-mode-PSL 
DOREI 


user-mode-PSL 
DOREI 


REI 


<EMPHASIS> 


<EMPHASIS> 


Marks a word or phrase for distinctive typographical treatment. 





FORMAT \ BOLD 


\ ITALIC 
<EMPHASIS > (text \ SMALLCAPS ) 


\ SMALL_BOLDCAPS 





ARGUMENTS TEXT 


Specifies the text to be emphasized. 


BOLD 
Indicates that the text should be set in a boldface font, rather than the default 
italic. 


ITALIC 


Indicates that the text should be set in the current italic font. This is the 
default. 


SMALLCAPS. 


Indicates that the text is to be set in small capital letters. 


SMALL_BOLDCAPS 


Indicates that the text is to be set in small capital letters. 





related tags * = <QUOTE> 
© = <UNDERLINE> 








restrictions None. 
required None. 
terminator 





DESCRIPTION The default form of emphasis is to set the text in an italic font. Use one of 
the optional keyword arguments to change the emphasis to another font. 
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oi 


<EMPHASIS> 





EXAMPLE 


<P>An <EMPHASIS>(overuse) of the <TAG>(emphasis) tag 
<EMPHASIS>(inevitably\bold) <EMPHASIS>(reduces\small_boldcaps) its 
<EMPHASIS> (smallcaps) (effectiveness) . 


{ 


This example may produce the following output: 


An overuse of the <EMPHASIS> tag inevitably REDUCES its EFFECTIVENESS. 
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<ENDCOPYRIGHT_PAGE> 


<ENDCOPYRIGHT_PAGE> 


Terminates the copyright page and optionally provides text that may be 
used on a document-type specific basis. 





FORMAT <ENDCOPYRIGHT_PAGE > /(identification)] 





ARGUMENTS _ identification 


Is a local convention for information to be supplied on the copyright page. 





restrictions This tag can only be used in the context of a copyright page. 





required None. 
terminator 





| DESCRIPTION The <ENDcOPYRIGHT_PAGE> terminates the copyright page and optionally 
provides text that may be used on a document-type specific basis. 





EXAMPLE 


<FRONT_MATTER> (front) 
<COPYRIGHT_PAGE> 
<PRINT_DATE>(March 1987) 
<COPYRIGHT_DATE> (1987) 
<ENDCOPYRIGHT_PAGE> 
<ENDFRONT_MATTER> 


This example shows the order in which the copyright page tags are 

used. Notice that you must enable the copyright page tags within the 
<FRONT_MATTER> tag. The output of this example is a separate copyright 
page in the front matter of the book, and the page contains the print and 
copyright dates. 


To see an example of all the front matter tags in their correct order, refer to 
the example in the <FRONT_MATTER> tag. 
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<ENDPART_PAGE> 


<ENDPART_PAGE> 


Terminates a part page and optionally specifies paging attributes for text 
that follows. 





FORMAT <ENDPART_PAGE> /(RENUMBER)] 





ARGUMENTS RENUMBER 
Specifies that the part page is to be numbered 1. If this argument is not 
specified, page numbering continues following the part page with the next 
odd-numbered page. 








restrictions This tag must be used in the context of a part page. 
required None. 
terminator 





DESCRIPTION The <ENDPART_PAGE> tag terminates a part page and optionally specifies 
paging attributes for text that follows. 


<ENDTITLE_PAGE> 


<ENDTITLE_PAGE> 


Terminates a title page and optionally specifies text to appear at the 
bottom of the title page. 





FORMAT <ENDTITLE_PAGE> (text) 





ARGUMENTS text 


Specifies a line to appear at the bottom of the title page. 








restrictions The <ENDTITLEPAGE> tag is valid only within the context of a title page. 
required None. 
terminator 





DESCRIPTION The <ENDTITLE_PAGE> tag terminates a title page and optionally specifies 
text to appear at the bottom of the title page. 





EXAMPLE Because the <ENDTITLE_PAGE> tag only terminates the title page, refer to the 
title page of this manual for an example of title page output. 


<EXAMPLE> 


<EXAMPLE> 


Labels the beginning of a formal example. 





FORMAT 


<EXAMPLE> (example-caption[ \ symbol-name]) 





ARGUMENTS 


related tags 


example-caption 

Specifies the text of the caption to be associated with the example, if any. 
The example caption and the associated example number will be written to 
the table of contents for the document. 


symbol-name 

Specifies the symbolic identifier to be associated with the example. The 
symbol identifier will be assigned a numeric value, which will be the current 
example number. The symbol and its value are placed in the symbol table. 


Symbol-names must not exceed 31 characters, and must only contain 
alphabetic letters, numbers, or underscores. Do not begin a symbol-name 
with an underscore. 





s <CODE_EXAMPLE> 


<EXAMPLE_ATTRIBUTES> 


<EXAMPLE_FILE> 


<EXAMPLE_SPACE> 


<INTERACTIVE> 


<VALID_BREAK> 











restrictions Cannot contain <TABLE>, <FIGURE>, or <MATH> tags. 
required <ENDEXAMPLE> 

terminator 

DESCRIPTION The <EXAMPLE> tag begins an example. 


If the body of the example spans more than a single page of text, the example 
caption is repeated on each page on which the example continues. 


If the example is more than a page, page breaks are handled automatically 

by the text processor. You can control the page breaking by using <PAGE> 
tags to specify explicit page breaks, or <VALID_BREAK> tags to specify good 
breaking points. 


Note that the presence of the symbol-name argument and the example- 
caption argument indicate that the example is a formal, numbered example. 


<EXAMPLE> 


When a floating figure or floating example precedes a multipage table (all 
tables not marked with the KEEP keyword are multipage), a succession of 
short pages may occur before the page on which the table begins. This is 
because a multipage table forces any previous floating figures or examples to 
be output before the table begins. 


If this situation occurs, code the preceding floating figures or examples with 
the KEEP keyword so that they will be kept with the text preceding them, 
and so result in better-balanced pages. 





EXAMPLE 


<EXAMPLE>(VAXcluster Multi-file Summary\multi_file_exam) 
<EXAMPLE_ATTRIBUTES> (WIDE) 
<EXAMPLE_FILE>(monitor_multi_file_summary) 

<ENDEXAMPLE> 


This example illustrates a one-page example, which uses the WIDE argument 
of the <EXAMPLE_ATTRIBUTE> tag. Assume that this example is the first 
example in the fourth chapter. 


The contents of the example are included using the <EXAMPLE_FILE> tag. 
The file that is included must contain either a code example or interactive 
example. 
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<EXAMPLE> 


This example may produce the following output: 


Example x-x VAXcluster Multi-file Summary 





Hoses + VAX/VMS Monitor Utility 
| AVE | TIME IN PROCESSOR MODES 
$n =S5 + MULTI-FILE SUMMARY 
Node: MOE CURLEY 


From: 15-APR-1984 18:17 


To: 15-APR-1984 20:17 15-APR-1984 20: 
Interrupt Stack 6.51 0 
Kernel Mode 25.73 0. 
Executive Mode 9.46 0 
Supervisor Mode 1.97 0 
User Mode 13.24 5 
Compatibility Mode 0.00 0 
Idle Time 23.61 0 

#5 secs + VAX/VMS Monitor Utility 

| AVE | PAGE MANAGEMENT STATISTICS 

feats + MULTI-FILE SUMMARY 

Node: MOE CURLEY 


From: 15-APR-1984 18:17 
To: 15-APR-1984 20:17 


Page Fault Rate 36.73 
Page Read Rate 14.28 
Page Read I/O Rate 1.20 
Page Write Rate 0.00 
Page Write 1/0 Rate 0.00 
Free List Fault Rate 8.60 
Modified List Fault Rate 5.83 
Demand Zero Fault Rate 12.96 
Global Valid Fault Rate 8.10 
Wrt In Progress Fault Rate 0.00 
System Fault Rate 4.92 
Free List Size 7586 . 30 
Modified List Size 87.69 





9-62 


15~-APR-1984 18: 


15-APR-1984 18: 
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<EXAMPLE_ATTRIBUTES> 


<EXAMPLE_ATTRIBUTES> 


Specifies attributes for the current example. 





FORMAT 


MUL TIPAGE 
<EXAMPLE_ATTRIBUTES> (| KEEP 


FLOAT 
[\ WIDE) 





ARGUMENTS 


MULTIPAGE 


Specifies that the example has multiple elements, and that each element is 
allowed to break at the start of a new page. This argument is required if the 
example will be on more than one page. When an example is continued, the 
example caption is automatically repeated at the beginning of each new page 
of output. 


KEEP 


Specifies whether the example is to be kept with the text that immediately 
precedes it. 


FLOAT 


Specifies whether the location of a one-page example is allowed to float. 
FLOAT indicates that if there is not enough room on the current page for the 
example, the text processor will fill the current page with the text from the 
source file that follows the <EXAMPLE> tag sequence, and place the example 
at the top of the next page of output. 


Float is the default for an example that has a caption and does not specify 
MULTIPAGE or KEEP. 


WIDE 


Specifies that the width of the example exceeds the document’s default width 
for text. Depending on the doctype, this argument can be interpreted as 
follows: 


e If the document style contains a left margin area that is normally used for 
headings, the example’s width will span that area as well as the normal 
text area. 


e If the document uses a multicolumn format, the example suspends 
multicolumn output while the example is processed. The example is 
output and the multicolumn output is then restored. 


e If the document style provides a range of sizes and styles for examples, 
this argument can be interpreted to mean that a specific size should be 
used for the example. 
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<EXAMPLE_ATTRIBUTES> 





related tags ¢  <EXAMPLE> 
: <EXAMPLE_FILE> 


° <EXAMPLE_SPACE> 








restrictions Must be enabled by <EXAMPLE> . 
required None. 
terminator 





DESCRIPTION By default, if an example does not fit on the current output page, it is placed 
at the top of the next page. The text that follows the example in the SDML 
file is used to fill the current output page. Thus, the example’s position in the 
text may change. It is said to “float.” 


If the example will be longer than a page, use the MULTIPAGE argument. 
The presence of the MULTIPAGE argument indicates that the example 
requires more than one page of output. The example will not be allowed to 
float. 


Formal examples that are coded with the default FLOAT argument may 
appear at the bottom of a page preceding text that should normally be at the 
top of a new page. Use <EXAMPLE_ATTRIBUTES> (KEEP) to force the formal 
example to be output before the new page. 





EXAMPLE 


<EXAMPLE>(Command Procedure for Adding a User\adduserex) 
<EXAMPLE_ATTRIBUTES> (WIDE\MULTIPAGE) 

<CODE_EXAMPLE> (WIDE) 

$ ! 

$! ADDUSER.COM -- Adds a new user to the system authorization file 


A 


USERDISK = "WRKD$:" ! Default disk for new users 
UAF = "$AUTHORIZE" 

ON CONTROLY THEN GOTO CLEANUP 

ON WARNING THEN GOTO CLEANUP 

OLDDIR = F$LOGICAL("SYS$DISK") + F$DIRECTORY() ' 

PREVPRIV = F$SETPRV("SYSPRV") 

IF .NOT. F$PRIVILEGE("SYSPRV") THEN GOTO NOPRIV 

SET DEFAULT SYS$SYSTEM 

1 

! Request account information 

{ 

INQUIRE USERNAME "Username" 

INQUIRE FULLNAME "Full name" 

SET TERMINAL/NOECHO 

INQUIRE PASSWORD "Password [''Username']" 

SET TERMINAL/ECHO 

$ IF PASSWORD .EQS. "" THEN PASSWORD = USERNAME 
<VALID_BREAK> 

$GET_GRP: 

$ INQUIRE GRP "UIC Group Number" 

$ IF GRP .EQS. "" THEN GRP = "x" 

$ WRITE SYS$OUTPUT "" 

$ WRITE SYS$OUTPUT "Determine the UIC from the following listing:" 
$ WRITE SYS$OUTPUT "" 


PHRAAPHPRAHRAHAFAHAHFHAAHAHHHSHEH 
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<EXAMPLE_ATTRIBUTES> 


$ UAF SHOW ['GRP',*]/BRIEF 
$ INQUIRE UIC 
$ IF UIC .EQS. "" THEN GOTO GET_GRP 
$ IF F$LOCATE("(",UIC) .EQ. F$LENGTH(UIC) .AND. - 
F$LOCATE("<", UIC) .EQ. F$LENGTH(UIC) THEN UIC = "[" + UIC + "]" 
$ INQUIRE ACCOUNT "Account Name [VMS]" 
$ IF ACCOUNT .EQS. "" THEN ACCOUNT = "VMS" 
$ INQUIRE PRIVS "Privileges [NONE] " 
$ IF PRIVS .NES. "" THEN PRIVS = "/PRIV=(" + PRIVS + ")" 
$ USERDIR = F$EXTRACT (0,9, USERNAME) 
$ INQUIRE TMP "Login Directory [''USERDIR']" 
$ IF TMP .NES. "" THEN USERDIR = TMP 
$ INQUIRE TMP "Login Device [''USERDISK']" 
$ IF TMP .NES. "" THEN USERDISK = TMP 
$ DQUOTA = 0 
$ IF F$SEARCH("''USERDISK'[0,0]QUOTA.SYS") .EQS. "" THEN GOTO NQO 
$ DQUOTA = 1 
<VALID_BREAK> 
$! 
$ ! Restore prior working environment 
$! 
$CLEANUP : 
$ SET TERMINAL/ECHO 
$ PREVPRIV = F$SETPRV(PREVPRIV) 
$ SET DEFAULT 'OLDDIR' 
$ EXIT 
$! 
: ! In case proper privileges are not set 
! 
s$NOPRIV: 


$ WRITE SYS$OUTPUT "You need SETPRV or SYSPRV privilege to run this procedure" 


$ 


GOTO CLEANUP 


<ENDCODE_EXAMPLE> 
<ENDEXAMPLE> 


This example illustrates the use of the <MULTIPAGE> argument. Two points 


especially should be noted: 


e¢ The <VALID_BREAK> tags in the <CODE_EXAMPLE> provide the text 


formatter with information about suitable places to break pages. 


¢ Because the example is wide, the WIDE argument was specified not only 
for the <EXAMPLE> tag, but also for the <CODE_EXAMPLE> tag within 


the example. 


<EXAMPLE_ATTRIBUTES> 


This example may produce the following output: 


Example x——-x Command Procedure for Adding a User 


! 
! ADDUSER.COM -- Adds a new user to the system authorization file 
{ 


USERDISK = "WRKD$:" ! Default disk for new users 
UAF = "$AUTHORIZE" 

ON CONTROLY THEN GOTO CLEANUP 

ON WARNING THEN GOTO CLEANUP 

OLDDIR = F$LOGICAL("SYS$DISK") + F$DIRECTORY()' 

PREVPRIV = F$SETPRV("SYSPRV") 

IF .NOT. F$PRIVILEGE("SYSPRV") THEN GOTO NOPRIV 

SET DEFAULT SYS$SYSTEM 

! 


! Request account information 
{ 
INQUIRE USERNAME "Username" 
INQUIRE FULLNAME "Full name" 
SET TERMINAL/NOECHO 
INQUIRE PASSWORD "Password [''Username']" 
SET TERMINAL/ECHO 
IF PASSWORD .EQS. "" THEN PASSWORD = USERNAME 
$GET_GRP: 
$ INQUIRE GRP "UIC Group Number" 
$ IF GRP .EQS. "" THEN GRP = "x" 
$ WRITE SYS$OUTPUT "" 
$ WRITE SYS$OUTPUT "Determine the UIC from the following listing:" 
$ WRITE SYS$OUTPUT "" 
$ UAF SHOW ['GRP',*]/BRIEF 
$ INQUIRE UIC 
$ IF UIC .EQS. "" THEN GOTO GET_GRP 
$ IF F$LOCATE("[",UIC) .EQ. F$LENGTH(UIC) .AND. - 

F$LOCATE("<", UIC) .EQ. F$LENGTH(UIC) THEN UIC = "(" + UIC + "]" 
$ INQUIRE ACCOUNT "Account Name [VMS]" 
$ IF ACCOUNT .EQS. "" THEN ACCOUNT = "VMS" 
$ INQUIRE PRIVS "Privileges [NONE]" 
$ IF PRIVS .NES. "" THEN PRIVS = "/PRIV=(" + PRIVS + ")" 
$ USERDIR = FS$EXTRACT(0,9, USERNAME) 
$ 
$ 
$ 
$ 
$ 
$ 
$ 
$ 
$ 


PFAHAHAHRHAAHAAAHAHAFHFHHAFAPAHFHAHHHHSH 


INQUIRE TMP "Login Directory [''USERDIR']" 
IF TMP .NES. "" THEN USERDIR = TMP 
INQUIRE TMP "Login Device [''USERDISK']" 
IF TMP .NES. "" THEN USERDISK = TMP 
DQUOTA = 0 
IF F$SEARCH("''USERDISK'[0,O0]QUOTA.SYS") .EQS. "" THEN GOTO NQO 
DQUOTA = 1 
! 
! Restore prior working environment 

$! 

$CLEANUP : 

$ SET TERMINAL/ECHO 

$ PREVPRIV = F$SETPRV(PREVPRIV) 

$ SET DEFAULT 'OLDDIR' 

$ EXIT 

$ ! 

$ ! In case proper privileges are not set 

$ ! 

$NOPRIV: 

$ WRITE SYS$OUTPUT "You need SETPRV or SYSPRV privilege to run this procedure" 

$ GOTO CLEANUP 
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<EXAMPLE_FILE> 


<EXAMPLE_FILE> 


Causes a separate file containing an example to be included in the source 
file. 





FORMAT 


<EXAMPLE_FILE> (file-spec) 





ARGUMENTS 


related tags 


restrictions 


required 
terminator 


file-spec 
Specifies the file containing the example. 





° <EXAMPLE> 
. <EXAMPLE_SPACE> 


bd <EXAMPLE_ATTRIBUTES > 





Cannot be used in an argument to a tag. 





None. 





DESCRIPTION 


The <EXAMPLE_FILE> tag causes the entire contents of the file to be included 
at this point in the SDML file. (It is identical in action to the <INCLUDE> 


tag.) 


The included file should be an SDML file containing a complete coded 
example, perhaps using <CODE_EXAMPLE> or <INTERACTIVE> tags. If the 
<EXAMPLE> tag specifies the WIDE argument, the included file must specify 
the WIDE argument on the appropriate tags. For more information on correct 
coding of examples and example files, including how to specify valid breaks, 
see Chapter 3. 


The <EXAMPLE_FILE> tag may have a logical name for an argument. The 
logical name can be defined by first entering an <INCLUDES_FILE> tag in the 
profile. The information in that tag is used to make the proper logical name 
assignment during processing. 





EXAMPLE 


See the example in the discussion of the <EXAMPLE> tag. 


<EXAMPLE_SPACE> 


<EXAMPLE_SPACE> 


Leaves space for an example that will be pasted in during final production. 





FORMAT 


<EXAMPLE_SPACE> /( ae ae a [\ text}) 





ARGUMENTS 


related tags 


restrictions 


required 
terminator 


value 

Specifies the size of the space in picas, a scale used by typesetters. There are 
approximately 6 picas to the inch. Thus, if the example is 4 inches high, you 
should specify 24 picas. The value must not exceed page depth limitations for 
the current document design. If you omit the value, a default value of 2 picas 
is used. 


FULL_PAGE 


If you specify the keyword FULL_PAGE, a full blank page is reserved for the 
example. 


text 
Specifies text to be printed in the center of the space. (For example, an art file 
number, a file name that contains the example, or some other note.) 





° <EXAMPLE> 


<EXAMPLE_FILE> 


<EXAMPLE_ATTRIBUTES> 


<REFERENCE> 





Can be used only in the context of an <EXAMPLE> tag. The value must not 
exceed page-depth limitations. 





None. 


DESCRIPTION The <EXAMPLE_SPACE> tag causes vertical space to be left on the output 


page for an example that will be pasted in by hand during final production. 
Any text supplied as the second argument is printed in the center of the 
space. 


<EXAMPLE_SPACE> 





EXAMPLE 


<EXAMPLE> (Completing Form DD-214\annotated_dd214_exam) 
<EXAMPLE_ATTRIBUTES> (wide) 


<EXAMPLE_SPACE>(12\Photo-reduced copy of the end of DD-214 here.) 
<ENDEXAMPLE> 


This example may produce the following output: 
Example x—x Completing Form DD-214 


Photo-reduced copy of the end of DD-214 here. 
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<FCMD> 


<FCMD> 


Specifies the keyword portion of a formatted command/parameter pair in 
a format section. 





FORMAT 


<FCMD> (keyword-part/ \ parameter-list]) 





ARGUMENTS 


related tags 


keyword-part 


Specifies the keyword portion of the keyword/parameter pair. 


parameter-list 
Lists the command parameters, if any. 


Parameters specified in this argument will differ on output from arguments 
specified using <FPARMS>. If you do specify <FCMD> with a null second 
argument, it is recommended that you explicitly declare the absence of 
parameters using <FPARMS> as follows: 


<FCMD>(KEYWORD-PART) <FPARMS>() 


If you do not specify a second argument, and if <FPARMS> is not specified, 
SDML will issue a warning message that it has no explicit declaration of 
parameters. 





. <FORMAT> 
° <FPARM> 


° <FPARMS> 











restrictions Enabled only within the context of the <FORMAT> tag. 

required None. 

terminator 

DESCRIPTION The <FcmD> tag identifies a command or keyword within a format section. 


You can specify the command or keyword’s argument list as the second 
argument to this tag. The <FCMD> tag should be used only in the context 
of a format section. A format section is established by <FORMAT> and 
<ENDFORMAT> . 


If the parameter-list argument text does not fit on one line, the text formatter 
chooses suitable line breaks based on the presence of spaces. 


<FCMD> 





EXAMPLES 


4 <FORMAT> 
<FCMD>(exit) <FPARMS>() 














<ENDFORMAT> 
Specifies a single command keyword. <FPARMS> is explicitly specified as 
null. The output from this code fragment is shown in Output Sample 1. 
2 <FORMAT> 
<FCMD>(append) <FPARMS>(input-file-spec output-file-spec) 
<ENDFORMAT 
This example specifies the command keyword and its parameters using both 
the <FCMD> and <FPARMS> tags. The output that this example produces is 
shown in Output Sample 2. 
Notice the difference between Output Sample 2 and 3. In Sample 2, space is 
left between the command-keyword and the parameter-list. In Sample 3, no 
space is left. This formatting is produced by the syntax used in the <FCMD> 
command. 
3 <FORMAT> 
<FCMD>(f£$element\ (element-number , delimiter ,string)) 
<ENDFORMAT 
This example specifies both the command-keyword and the parameter-list 
arguments to the <FCMD> tag. The output that this example produces is 
shown in Output Sample 3. 
E\ = <FORMAT> 
<FCMD>(set protection\ [=code] <keyword>(/DEFAULT) ) 
<ENDFORMAT 
This example illustrates how to control the interpretation of keywords tagged 
with the global <KEYWORD> tag when they are mixed in with the parameter 
list of a format specification. The output that this example produces is shown 
in Output Sample 4. 
OUTPUT exit 
SAMPLE 1 
OUTPUT append input-file-spec output-file-spec 
SAMPLE 2 
OUTPUT f$element(element-number, delimiter, string) 
SAMPLE 3 
OUTPUT set protection/=code]//DEFAULT 
SAMPLE 4 
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<FIGURE> 


<FIGURE> 


Labels the beginning of a figure. 





FORMAT 


<FIGURE> [(figure-caption[ \ symbol-name))] 





ARGUMENTS 


related tags 


figure-caption 

Specifies the text of the caption to be associated with the figure. The figure- 
caption and the associated figure number will be written to the table of 
contents for the document. 


symbol-name 

Specifies the symbolic identifier to be associated with the example. The 
symbol-name is assigned a numeric value, which becomes the current figure 
number. The symbol-name and its value are placed in the symbol table. 


All symbol-names must not exceed 31 characters, and must only contain 
alphabetic letters, numbers, or underscores in them. Do not begin a symbol- 
name with an.underscore. 





© <FIGURE_ATTRIBUTES > 


<FIGURE_FILE> 


° <FIGURE_SPACE> 


<LINE_ART> 


<REFERENCE> 


<ICON> 


<ICON_FILE > 











restrictions None. 

required <ENDFIGURE> 

terminator 

DESCRIPTION The <rFiGuRE> tag is used to label formal and informal figures. A formal 
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figure is listed in the table of contents, has a unique number by which it is 
cross-referenced from other parts of your book, and has a caption that labels 
it. An informal figure does not appear in the table of contents and has no 
caption or number identifier. 


The presence of a figure-caption and symbol-name indicate that the figure is 
a formal, numbered figure. 


<FIGURE> 


The figure-caption argument of this tag specifies the text of the caption 
associated with the figure. The figure caption and the associated figure 
number will be written to the table of contents for the document. If the 
body of the figure spans more than a single page of text, the figure caption is 
repeated on each page on which the figure continues. 


The symbol-name specifies the symbolic identifier to be associated with the 
figure. The symbol identifier will be assigned a numeric value, which will be 
the current figure number. The symbol and its value are placed in the symbol 
table. 


A formal figure is sometimes long. If you think one of your figures 
will be longer than a page, label it as a multipage figure in the 
<FIGURE_ATTRIBUTES> tag. 


If the figure does not fit on the current output page, the figure is placed at the 
top of the next page. The text that follows the example in the SDML file is 
used to fill the current output page. Thus, the figure’s position in the text may 
change or “float.” If floating is undesirable you must use the KEEP argument 
to fix the figure at its current position in the text. If it does not fit on the page, 
the page is terminated, and the figure begins on a new page. Use of KEEP 
ensures that the figure and its accompanying text remain in the same order. 
However, KEEP should be used sparingly and only where examples are short 
and frequent, in order to avoid excessively short pages. 


When a floating figure or floating example precedes a multipage table (all 
tables not marked with the KEEP keyword are multipage), a succession of 
short pages may occur before the page on which the table begins. This is 
because a multipage table forces any previous floating figures or examples to 
be output before the table begins. 


If this situation occurs, code the preceding floating figures or examples with 
the KEEP keyword so that they will be kept with the text preceding them, 
and so result in better-balanced pages. 





EXAMPLES 


<FIGURE>(Example of Terminal-Created Art\transfer_vector_exam) 
<FIGURE_ATTRIBUTES> (KEEP) 
<LINE_ART> (KEEP) 


Shareable Image Executable Image 
t----------- + +------------ + 
+----| Vector A |<------- + | | 
ono nen n ne + | | : | 
| +--| Vector B |<---+  +----- Invoke A | 
|. fi aeerssessens= + | | : | 
+r==>]| | | | . | 
| | Routine A | S tetitatatatel Invoke B_ | 
1 | | | | 
Il, steesecseesss + | | 
+->| | 5 eae + 
| Routine B | 
| 
t----------- + 


<ENDLINE_ART> 
<ENDF IGURE> 


In this example, the <FIGURE_ATTRIBUTES> tag contains a KEEP argument, 
to specify that the figure should be kept with the immediately preceding text. 
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<FIGURE> 


The <LINE_ART> tag also has a KEEP argument, to specify that the figure 
should not break across pages. 


The figures you are able to create using your terminal keyboard may be 
adequate for draft purposes, but will not be acceptable in the context of 
typeset output. This example may produce the following output: 


Figure x—x Example of Terminal-Created Art 





Shareable Image Executable Image 
tonccec cnn + toccc nnn + 
tase | Vector A: [<=2-e+S + | 
| toon nne nnn + | | . | 
| +--| Vector B |<---+ +----- Invoke A | 
lik tapseaar esas + | ; | 
+--->| | | | ; | 
| | Routine A | #5eosee554 Invoke B 
| | | | | 
J te---------- + | 
+->| | taco cn nen + 
| Routine B | 
| | 
+----------- + 





FJ] = <DEF INE_SYMBOL> (ZK_2347\2) 
<FIGURE> (Illustration of the Workshop Layout Showing Forklift\ZK_2347) 
<FIGURE_SPACE>(FULL_PAGE\An illustration of the memory management workshop 
analogy, complete with picture of the forklift.) 
<ENDF IGURE> 


This example illustrates how to code a figure that will take one page. This 
example may produce output like that found on the following page. 
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<FIGURE> 


Figure x—-x_ Illustration of the Workshop Layout Showing Forklift 


An illustration of the memory management workshop 
analogy complete with picture of the forklift. 


9-75 


<FIGURE> 
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<FIGURE>(Discreet Portions of the Process Header\proc_head_fig) 
<FIGURE_ATTRIBUTES> (Multipage) 

<FIGURE_SPACE>(15\Shows general structure of process header) 
<FIGURE_SPACE>(15\Shows structure of process page tables) 
<FIGURE_SPACE>(15\Shows structure of different forms of page table entry) 
<ENDF IGURE> 


This example shows how to code a figure that is allowed to extend over 
several pages. The MULTIPAGE argument to the <FIGURE_ATTRIBUTES> tag 
tells the text formatter that the figure is more than one page. 


<FIGURE> 


Figure x—x Discrete Portions of the Process Header 


Shows general structure of process header 


Figure x——-x Cont'd. on next page 
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_- <FIGURE> 


Figure x—x (Cont.) Discrete Portions of the Process Header 


Shows structure of process page tables 


Figure x—x Cont'd. on next page 


9-78 


<FIGURE> 


Figure x—x (Cont.) Discrete Portions of the Process Header 


Shows structure of different forms of page table entry 


<FIGURE> 


4] <P> ... and then procedes to linking the object 
modules into an executable image. (You are not required to 
put object modules in a library. You can link them directly.) The following 
figure illustrates the implementation cycle. 


<FIGURE> 
<FIGURE_SPACE> (17\ZK- -8769--84) 
<ENDF IGURE> 

<P> 

The first cycle shows that 


This example shows how to code an informal figure that appears within text 
without floating, without a number, and without a caption. It may produce 
the following output: 


. and then proceeds to linking the object modules into an executable image. 
(You are not required to put object modules in a library. You can link them 
directly.) The following figure illustrates the implementation cycle. 


ZK-8769-84 


The first cycle shows that... 
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<FIGURE_ATTRIBUTES> 


<FIGURE_ATTRIBUTES> 


Specifies the placement of a figure on the page. Also specifies valid page 
breaks for that figure. 








FORMAT MUL TIPAGE 
<FIGURE_ATTRIBUTES> (| KEEP 
FLOAT 
[\ WIDE}) 
ARGUMENTS MULTIPAGE 


Specifies that the figure has multiple elements, and that each element is 
allowed to break at the start of a new page. This argument is required if the 
figure will be on more than one page. When a figure is continued, the figure 
caption and figure column heads, if any, are automatically repeated at the 
beginning of each new page of output. 


KEEP 


Specifies that the figure is to be kept with the immediately preceding text. 
This is the default for a figure without a caption. 


FLOAT 


Specifies whether the location of a one-page figure is allowed to float. FLOAT 
indicates that if there is not enough room on the current page for the figure, 
the text processor will fill the current page with the text from the source file 
that follows the <FIGURE> tag sequence, and place the figure at the top of 
the next page of output. 


Float is the default for a figure that has a caption and does not specify 
MULTIPAGE or KEEP. 


WIDE 


Specifies that the width of the figure exceeds the document’s default width 
for text. Depending on the document type, this argument can be interpreted 
as follows: 


e If the document style contains a left margin area that is normally used for 
headings, the figure’s width will span that area as well as the normal text 
area. 


e If the document uses a multicolumn format, the figure suspends 
multicolumn output while the figure is processed. The figure is output 
and multicolumn output is then restored. 


e If the document style provides a range of sizes and styles for figures, this 
argument may be interpreted to mean that a specific size should be used 
for the figure. 
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<FIGURE_ATTRIBUTES> 


related tags 


restrictions 


required 
terminator 





e <FIGURE> 
od <FIGURE_FILE> 


° <FIGURE_SPACE> 





This tag must be used within the context of a <FIGURE> tag. 





None. 





DESCRIPTION This tag is used in the context of a formal figure. Use <FIGURE_ATTRIBUTES> 


to adjust the pagination and placement of the figure. 


A formal figure is sometimes long. If you think one of your figures will be 
longer than a page, use the MULTIPAGE argument. Your figure will then 
be placed on the current page and continued on following pages, as space 
permits. 


A multipage figure can contain one or more elements (that is, one or more 
<FIGURE_FILE> , <FIGURE_SPACE> , and <CODE_EXAMPLE> tags). 


If your multipage figure (consisting of a single <CODE_EXAMPLE> ) contains 
no blank lines, you might want to insert <VALID_BREAK> tags in the figure. 
The <VALID_BREAK> tags specify reasonable page breaking points. See the 
description of the <VALID_BREAK> tag for more information. 


A one-page (or smaller) figure’s position in the output file can change. If the 
figure does not completely fit on the current page, the entire figure is placed 
at the top of the next page. The text that follows the example in the SDML 
file then is used to fill the current output page. When the figure’s position can 
change, the figure is said to float. 


Floating is the default condition for a figure that has a caption and fits on 
one page. If you want the placement of a figure without a caption to float, 
you must specify the FLOAT argument if your figure fits on one page. A 
multipage figure never floats. 


The argument KEEP will override the default FLOAT condition for a figure 
with a caption. 


Figures that are coded with the default FLOAT argument may appear at the 
bottom of a page preceding text that should normally be at the top of a new 
page. Use <FIGURE_ATTRIBUTES> (KEEP) to force the figure to be output before 
the new page. 





EXAMPLE 
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See the first example in the <FIGURE> tag. 


<FIGURE_FILE> 


<FIGURE_FILE> 


Includes a graphics file in your output file if the output device has graphics 





capability. 
FORMAT <FIGURE_FILE> (target-device 
\ file-spec 
\ SPACE 
\ vertical-size 
[ \ position)}) 





ARGUMENTS _ target-device 
Specifies a keyword indicating the output device for the graphics file. 
Keywords are provided both for devices that do (LN03 and PS) and do 
not (LINE, MAIL, and TERMINAL) support graphics. Each keyword allows 
you to insert the necessary amount of white space for the specific output 
device; keywords for devices that do not support graphics allow you to insert 
blank space in place of a figure. The following table lists the output devices 
and expected output for each keyword. 


Keyword Device Output 
LNO3 LNO3 Laser Printer The specified sixel graphics file is 
output as a figure. 
PS PRINTSERVER 40 or The specified POSTSCRIPT 
LNO3R SCRIPTPRINTER graphics file'is output as a figure. 

LINE Line Printer If specified, blank space is output 
MAIL with the file-spec argument 
TERMINAL written in that blank space. Only 


one of these three keywords 
should be used to indicate a 
monospaced destination. 


‘PostScript graphics files must conform to the Encapsulated PostScript File Format 
published by Adobe Systems Incorporated. 


If you specify <FIGURE_FILE> for a given device and subsequently process 
the file on another output device, no output will appear in the position of the 
<FIGURE_FILE> tag. 


file-spec 
Specifies the graphics file. 


SPACE 


Lets you reserve blank space in the output file for a figure. Use this keyword 
to reserve space for art that will be pasted in at a later date or when you 
expect to process a file for more than one output device, but do not have 
graphics files for all devices. 
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<FIGURE_FILE> 


related tags 


restrictions 


required 
terminator 


vertical-size 

Specifies the vertical size of the printed graphic in picas (six picas equal an 
inch). This argument may be a nonnegative integer or decimal number, 
including zero. 


position 
Specifies an optional keyword that determines how the graphic aligns in 
relationship to the text: 


¢ null — aligns with the normal left text margin. 


e WIDE — aligns at the leftmost position of the image area (if your format 
has a wide left gutter). 





° <ICON> 
7 <ICON_FILE> 
<FIGURE> 


sd <SET_FIGURE_FILE_SPACING_.DEFAULT> 





You must use an LNO3 or PosTScrirT laser printer to print graphics files. 
You must use the <FIGURE_FILE> tag in the context of the <FIGURE> tags. 


If you use the <FIGURE_FILE> tag in a file that you process for multiple 
output devices, you must supply a tag for each device, using the SPACE 
keyword for devices for which you do not have graphics. 





None. 


La 
DESCRIPTION The <FIGURE_FILE> tag enables you to automatically include graphics files 
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for printing along with your text in the output file. 


To ensure that your figure is the right size for inclusion with your output, 
follow this procedure: 


1 Create and print your graphics file full size (100 percent). 
2 Measure it. 


3 If the figure at 100 percent is the desired size and will fit on the page, 
incorporate that measurement into the <FIGURE_FILE> tag. Otherwise, 
calculate a percentage reduction and use the graphics editor to reduce 
the figure to the desired size. Print and measure the graphics file and 
incorporate the measurement in the <FIGURE—FILE> tag. 


4 Process the SDML file and print the output. 


<FIGURE_FILE> 


5 Evaluate the result. If it is satisfactory, you are finished. Otherwise, 
change either of the following. 


¢ One or both keywords specified in <FIGURE_FILE> to correct the 
alignment, spacing, or both, for the figure. 


e The graphics file itself to correct the size, content, or both 


Because there is an interaction between changing the contents or size of 
the graphics file and specifying its placement in the <FIGURE_FILE> tag, 
satisfactory results may require several loops through the process, much like 
coding complicated tables. Refer to Chapter 3 for information on coding 
tables. 


If you plan to process your file for more than a single destination, you can 
use multiple <FIGURE_FILE> tags to ensure that the appropriate figure will be 
included for the appropriate destination; an example of this coding is given 
in the following “Examples” section. If you use multiple <FIGURE_FILE> tags 
in this way, you should specify only a single <FIGURE_FILE> tag for all the 
monospaced destination keywords (MAIL, TERMINAL, or LINE). 





EXAMPLES 


<FIGURE>(The Front View) 
<FIGURE_FILE> (LNO3\frontpanel .six\6) 


<ENDFIGURE> 

This example shows how to code a numbered figure. 
<FIGURE> 
<FIGURE_FILE>(LNO3\example1.six\10) 
<ENDF IGURE> 

This example shows how to code an unnumbered figure. 
<FIGURE> 


<FIGURE_FILE>(LNO3\SANTA.SIX\15) 
<F IGURE_FILE>(PS\SANTA.PS\15) 

<F IGURE_FILE> (LINE\SPACE\10) 
<ENDF IGURE> 


This example shows how to use multiple <FIGURE_FILE> tags so that your 
figure will process for multiple destinations. If this file is processed for a 
POSTSCRIPT destination, the file included would be SANTA.PS. If this file is 
processed for an LNO3 laser printer destination, the file included would be 
SANTA.SIX. If this file is processed for a line printer destination no file would 
be included, but instead 10 blank lines would be reserved for the graphic. 
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<FIGURE_FILE> 


A sixel file included into a document as in the previous code example may 
have the following output: 





ZK-7713-HC 
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<FIGURE_SPACE> 


<FIGURE_SPACE> 


Marks the space required for a figure that will be pasted in during final 
production. 





FORMAT 


<FIGURE_SPACE> (| ae pace [\ text}) 





ARGUMENTS 


related tags 


restrictions 


required 
terminator 


value 

Specifies the amount of vertical space to be left on the page. The value should 
be specified in picas, a scale used by typesetters. There are approximately 6 
picas to the inch. Thus, if the figure to be pasted in is 4 inches high, you 
should specify 24. If you do not specify a value, a default value of 2 is used. 


FULL_PAGE 


Specifies that a full blank page is reserved for the figure. 


text 

Specifies text that describes the status of the figure, an art file number or the 
words “To Be Set.” The text is output in the middle of the space left for the 
figure. 





° <FIGURE> 

e <FIGURE_ATTRIBUTES > 
bd <FIGURE_FILE> 

° <REFERENCE> 

° <FIGURE_SPACE> 


e° <LINE_ART> 





Must be used in the context of a <FIGURE> tag. 


The value of the <FIGURE_SPACE> tag must not exceed page depth 
limitations. 





None. 
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<FIGURE_SPACE> 





DESCRIPTION The <FIGURE_SPACE> tag causes a blank space to be left on the page for a 
figure that will be pasted in by hand during final production. 


If you specify some descriptive text in the second argument, that text is output 
in the middle of the space left for the figure. 





EXAMPLE | See the example in the discussion of the <FIGURE> tag. 
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<FILE_SPEC> 


<FILE_SPEC> 


Allows you to use a file specification that contains angle brackets as an 
argument to an SDML tag without VAX DOCUMENT interpreting that file 
specification as an SDML tag. 





FORMAT 


<FILE_SPEC> (file-specification) 





ARGUMENTS 


related tags 


restrictions 


file-specification 
The file specification that contains angle brackets. 





° <ELEMENT> 


° <EXAMPLE_FILE> 


<FIGURE_FILE> 


<ICON_FILE> 


<INCLUDE> 


<INCLUDES_FILE> 


<TABLE_FILE> 





None. 





DESCRIPTION The <FILE_sPEC> tag allows you to use a file specification containing angle 


brackets as the file-spec argument to SDML tags that let you include external 
files, such as <INCLUDE> and <FIGURE_FILE>. A complete list of such tags 
is found in the “Related Tags” section of this tag description. 


Some keyboards do not provide square brackets ([) and (]), so it is common 
for the directory portion of a file specification to be delimited by angle 
brackets. Because VAX DOCUMENT would normally interpret text within 
angle brackets as an SDML tag, the <FILE_SPEC> tag converts any angle 
brackets in its argument into the corresponding square brackets. 


You do not have to use the <FILE_SPEC> tag to specify logical names in a 
file specification whose equivalence strings contain angle brackets. 
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<FILE_SPEC> 





EXAMPLE 


<figure_file>(1n03\<file_spec>(mydisk:<figure>diagram.six) \20) 


The directory name in this file specification would normally be seen as a 
<FIGURE> tag, which would lead to erroneous results. Because the file 
specification is used as an argument to the <FILE_SPEC> tag, the angle 
brackets will be converted to square brackets before the apparent <FIGURE> 
tag is recognized. Thus, the example is equivalent to the following. 


<figure_file>(1n03\mydisk: [figure] diagram.six\20) 
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<FINAL_CLEANUP> 


<FINAL_CLEANUP> 


Provides explicit formatting instructions for the text formatter to be used 
for final formatting and cleanup. 








FORMAT COLUMN_BREAK 
<FINAL_CLEANUP> ( } L/NE_BREAK ) 
PAGE_BREAK 
SPECIAL __BREAK 
ARGUMENTS COLUMN_BREAK 


related tags 


restrictions 


required 
terminator 


Specifies that a new column of text is to be started at the place where the 
<FINAL_CLEANUP> tag occurs. This argument is only valid in a two-column 
design (ARTICLE or REPORT.TWOCOL) and should be used only to make 
the final documentation look better. 


LINE_BREAK 


Specifies that the text formatter is to place the remaining text in the paragraph 
onto a new line of output. 


PAGE_BREAK 


Specifies that the text formatter should place following text on a new page of 
output. 


SPECIAL_BREAK 


Specifies a special break when vertical spacing appears to be lost. In some 
circumstances, the output of a two-column page may have had some of 

its vertical spacing lost due to the text formatter processing, for example, 

a heading tag may not have any space before it. The SPECIAL_BREAK 
argument should be used only if there is a spacing problem and only after 
you are ready to give your document a final format check, because changes to 
the source file may help the text formatter resolve the spacing problem. 





e <COLUMN> — ARTICLE and REPORT.TWOCOL 
e <LINE> 


. <PAGE> 





None. 
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<FINAL_CLEANUP> 





DESCRIPTION The <FINAL_CLEANUP> tag is not a generic markup tag; it explicitly instructs 
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the text formatter to change aspects of a page makeup. 


In a single-column doctype, the <FINAL_CLEANUP> tag enables you to 
specify line breaks and page breaks using the LINE BREAK and PAGE— 
BREAK keyword arguments. In a two-column doctype, you can use the 
COLUMN~_BREAK keyword argument to start a new column of text. The 
SPECIAL_BREAK keyword argument is used only rarely at the final stage of 
production to place “finishing touches” into your document. 


When you are working with the ARTICLE or REPORT.TWOCOL doctypes, 
you may need to make some final adjustments when your text is complete. 
The text formatter makes formatting decisions based on your source file. It 
is more difficult for the text formatter to create a well-formatted two-column 
page than it is a well-formatted one-column page. Therefore, the output of 
these doctypes may need additional “finishing touches” during the last stage 
of document production. 


<FOOTNOTE> 


<FOOTNOTE> 


Places a footnote character in text, using the character specified in the 
tag’s argument, and places the footnote text at the bottom of the page. 





FORMAT 


<FOOTNOTE> (char \ footnote-text) 





ARGUMENTS 


related tags 


restrictions 


char 

Specifies the footnote character. The character can be a single character, 
a number, or one of the following keywords denoting special characters 
associated with footnote references: 


DAG (t) 
DDAG (t) 
R (®) 

S (8 

™ ey 


When placing a footnote in a table, you must use a number or one of the 
keywords as the footnote character. 


If you use more than one of the keywords allowed for table footnotes, you 
should declare them in the following order to ensure that the footnotes print 
in the correct order at the bottom of the page: 


1 T™™ 
2 R 
3.5 
4 DAG 
DDAG 
footnote-text 


Specifies the text of the footnote. 





° <FOOTREF> 


e <FOOTNOTE_TEXT> 





Invalid in math. 


No more than four footnotes may be placed within a stacked list or a 
monospaced example. 


The following restrictions apply to footnotes within tables: 


e There can be no more than twelve footnotes in a table. If you use a 
nonnumeric footnote character, there can be no more than seven numeric 
footnotes. 


9-93 


<FOOTNOTE> 


required 
terminator 


e All table footnotes must be declared at the top of the table using a 
<FOOTNOTE> tag just after the <TABLE_SETUP> tag. <FOOTNOTE> tags 
must not be specified in a nested table. 


¢ Callouts within the body of a table must be labeled with a <FOOTREF> 
tag. It is the <FOOTREF> tag that causes the footnote character to appear. 


e Footnotes in the body of a multipage table appear at the bottom of a page 
only if they are called out on that page. 


¢ Footnotes called out in the heading of a multipage table appear at the 
bottom of each page of the table. 


¢ Footnotes on a title page and copyright page should be specified using 
the <FOOTNOTE_TEXT> tag. 





None. 





DESCRIPTION 


The <FOOTNOTE> tag causes a footnote character to appear in text at the 
place where the tag is located. The text of the footnote is specified as the 
second argument to the tag, and appears at the bottom of the page. 





EXAMPLES 


1 <P>The <TAG>(footnote) tag may produce output that looks like 
this .<FOOTNOTE>(1i\Note how 
footnote text appears at the bottom of the page.) 


ND} 


This example may produce the following output: 


The <FOOTNOTE> tag may produce output that looks like this.! 


<TABLE>(Rules for Determining Expression Modes\express_modes_tab) 


<TABLE_ATTRIBUTES> (MULTIPAGE) 


<TABLE_SETUP> (2\43) 


<FOOTNOTE>(1\A footnote in a table.) 
<TABLE_HEADS>(Expression\Value Type) 
<TABLE_ROW>(Integer value\Integer) 
<TABLE_ROW> (String value\String<FOOTREF>(1)) 
<TABLE_ROW>(Integer lexical function\Integer) 
<TABLE_ROW>(String lexical function\String) 
<TABLE_ROW>(Integer symbol\Integer) 
<TABLE_ROW>(String symbol\String) 
<TABLE_ROW>(Any value .AND. or .OR. any value\Integer) 
<TABLE_ROW>(Any value\Integer) 
<TABLE_ROW>(Any value\Integer) 


<ENDTABLE> 


This example shows how to produce a two-column table that contains a 
footnote. A <FOOTNOTE> tag is placed directly after the <TABLE_SETUP> 
tag to declare the existence of a footnote and to identify the footnote text. 
A <FOOTREF> tag then is placed in the exact location of the footnote 
superscripted reference mark in the table. 


Make sure to place the <FOOTREF> tag within the argument to a <TABLE_ 
ROW> tag. 


1 Note how footnote text appears at the bottom of the page. 
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<FOOTNOTE> 


The example may produce the following output: 


Table x—x Rules for Determining Expression Modes 


Expression Value Type 
Integer value Integer 
String value . String! 
Integer lexical function Integer 
String lexical function String 
Integer symbol Integer 
String symbol String 

Any value .AND. or .OR. any value Integer 

Any value Integer 

Any value Integer 


1A footnote in a table. 


<FOOTNOTE_TEXT> 


<FOOTNOTE_TEXT> 


Specifies the text of a footnote in the context of a heading, title page, or 
copyright page. 





FORMAT 


<FOOTNOTE_TEXT > (char \ text) 





ARGUMENTS 


related tags 


restrictions 


required 
terminator 


char 

Specifies the footnote character. The character can be a single character 
or number, or it can be one of the following keywords denoting special 
characters associated with footnote references: 


DAG (t) 
DDAG (t) 
R (®) 

S (8) 
TM ( ) 


text 
Specifies the text associated with the footnote. 





° <FOOTREF> 


° <FOOTNOTE> 





Required when footnotes are specified in the context of header-level text 
and title pages/copyright pages. Must not be used for table footnotes. The 
<FOOTNOTE_TEXT> tag must follow the related <FOOTREF> tag in the 
source file. 





None. 





DESCRIPTION The tag <FOOTNOTE_TEXT> allows you to specify the text, placement, or 
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both, of a footnote in the following special circumstances: 


e When you want to specify a footnote in an argument to a header-level 
tag (<HEAD1>, <HEAD2>, etc.) 


¢ When you want to specify footnote text related to a footnote character on 
the title page of a document. 


In all other cases, you should use the <FOOTNOTE> tag. 


<FOOTNOTE_TEXT> 





EXAMPLES 


<HEAD1>(Introduction to The News Today<footref>(TM)) 
<footnote_text>(TM\The News Today 

is a trademark of the American Television 

Society.) 


This example illustrates the use and placement of the <FOOTNOTE_TEXT> tag 
and its related <FOOTREF> . 


<front_matter> 

<TITLE_PAGE> 

<product>(CATCHUP<footref>(TM) ) 

<title>(Guide to Growing Premium Fruit Bearing Plants) 
<ABSTRACT>(June 1986) 

This document describes how to cultivate smooth-skinned 
tomato plants. 

<ENDABSTRACT> 


<footnote_text>(TM\CATCHUP is a trademark of Tomato Magnates, Inc.) 
<ENDTITLE_PAGE> 


This example illustrates the placement of a footnote on the title page of a 
document. The exact placement of the footnote, in the final output, is based 
on the document-specific design specified by the book designer. 
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<FOOTREF> 


<FOOTREF> 


Creates one or more footnote characters in text or in a table using the 
footnote numbers or characters as arguments. 





FORMAT 


<FOOTREF> (char-1 [\ char-2... \ char-9]) 





ARGUMENTS 


related tags 


char-7...9 


The character(s) for the footnote. A character can be a single character or 
number, or it can be one of the following special characters associated with 
footnote references: 


DAG (t) 
DDAG (t) 
R (°) 

S (8 

ai Je 


In a table, the reference must be to a number or to one of the special 
characters. 





° <FOOTNOTE> 


° <FOOTNOTE_TEXT> 











restrictions Invalid in math. 
Can only be used at the end of an argument list and cannot be embedded in 
text; the end of an argument list is indicated by a backslash (\) or a closing 
parenthesis ()). 

required None. 

terminator 

DESCRIPTION The <FOOTREF> tag causes as many as nine superscripted characters to 


appear in the text at the place where the tag is located in the SDML file. 
There are two occasions that require use of the <FOOTREF> tag: 
e Where the same footnote in text needs to be called out more than once 


e Wherever a footnote is called out in a table 


If you have a footnote in the text to which you want to refer more than 
once, you should use a <FOOTNOTE> tag to label the first occurrence of the 
footnote and the <FOOTREF> tag to label the subsequent characters to that 
note. 


The text formatter does not automatically repeat text footnotes if references 
are output on more than one page. 


<FOOTREF> 


If you have one or more footnotes within a table, you must declare the 
footnotes using the <FOOTNOTE> tag just after the <TABLE_SETUP> tag. 
You can then use the <FOOTREF> tag to label the characters within the table 
body. Within a table, the presence of the <FOOTREF> tag causes the text of 
the footnote to appear at the bottom of the table, rather than at the bottom of 
the page. If the table is longer than a single page, and if the <FOOTREF> tag 
appears multiple times, the footnote text appears at the bottom of the table 
on each page containing the reference. 


Make sure to place the <FOOTREF> tag within the argument to a 
<TABLE_ROW> tag. 





EXAMPLE 


<P>The macro format for a $GETDVI request is:<FOOTNOTE>(1\The 

eighth (last) 
argument is not used; it is reserved for future use.) 
<CODE_EXAMPLE> 

$GETDVI [efn] , [chan], [devnam] ,itmlst, [iosb] , [astadr] , lastprm] 
<ENDCODE_EXAMPLE> 
<P>The high-level language format for a $GETDVI request is:<FOOTREF>(1) 
<CODE_EXAMPLE> 

SYS$GETDVI([efn] , [chan] , [devnam] ,itmlst, [iosb] , [astadr] , [astprm] ) 
<ENDCODE_EXAMPLE> 


This example may produce the following output: 
The macro format for a $GETDVI request is:! 
$GETDVI [efn],[chan],[devnam],itmlst,[iosb],[astadr],[astprm] 
The high-level language format for a $GETDVI request is:! 
SYS$GETDVI([efn],[chan],[devnam],itmlst,[iosb],[astadr],[astprm]) 


1 The eighth (last) argument is not used; it is reserved for future use. 
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<FORMAT> 


<FORMAT> 


Enables <FCMD>, <FPARMS>, and <FPARM> to distinguish formatted 
command keywords and parameters. 





FORMAT <FORMAT> /[( Heading-text | 
WIDE 





ARGUMENTS _heading-text 
Specifies a heading. 


WIDE 


Indicates, for document styles in which the left margin is indented, that the 
body of the formatted text should be extended into the margin. 





related tags ¢ = <FCMD> 
. <FPARM> 


° <FPARMS> 


restrictions Invalid in math, monospaced examples, tables, and figures. 

a Da a EER ED 
required <ENDFORMAT> 
terminator 


EXAMPLE See the examples in the discussion of the <FCMD> tag. 
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“<FPARM> 


<FPARM> 


Specifies a parameter to be formatted following <FPARMS> , aligned under 
the parameter list portion of a keyword/parameter list pair. 





FORMAT 


<FPARM> (parameter-list) 





ARGUMENTS 


related tags 


parameter-list 
Lists additional command parameters, if any. 





. <FCMD> 
e <FORMAT> 


. <FPARMS> 








restrictions Enabled only within <FORMAT> . 

required None. 

terminator 

EXAMPLE See the examples in the discussion of the <FCMD> tag. 


9-101 


<FPARMS> 


<FPARMS> 


Specifies the parameter portion of a formatted command/parameter pair 
in a format section. 





FORMAT 


<FPARMS> (parameter-list) 





ARGUMENTS 


related tags 


restrictions 


parameter-list 
Lists the command parameters, if any. If there are no parameters, you can 
specify the argument as null: <FPARMS> . 





° <FCMD> 
° <FORMAT> 


° <FPARM> 





Enabled only within <FORMAT> . 








required None. 
terminator 
EXAMPLE See the examples in the discussion of the <FCMD> tag. 
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<FRONT_MATTER> 


<FRONT_MATTER> 


Begins the front matter of a book. 





FORMAT 


<FRONT_MATTER> [(symbol-name)] 





ARGUMENTS 


related tags 


symbol-name 
Specifies the term that you assign to the front matter. A symbol-name 
argument is required if the front matter is to be part of a bookbuild. 


Symbol-names must not exceed 31 characters, and must only contain 
alphabetic letters, numbers, or underscores in them. Do not begin a symbol- 
name with an underscore. 





e See the list of tags in the description. 











restrictions None. 

required <ENDFRONT_MATTER> 

terminator 

DESCRIPTION The <FRONT_MATTER> tag enables the tags that create the front matter of a 


book. The following tags are used to create the front matter: 


<ABSTRACT> 


<CONTENTS_FILE> 


<COPYRIGHT_DATE> 


<COPYRIGHT_PAGE> 


<FRONT_MATTER> 


<ORDER—_NUMBER> 


<PREFACE> 


<PREFACE_SECTION > 


<PRINT_DATE> 


<REVISION _INFO> 


<TITLE> 


<TITLE_PAGE> 


Each of these tags is listed alphabetically within this chapter. The order that 
these tags are used is shown in the following example. 


<FRONT_MATTER> 





EXAMPLE 


<FRONT_MATTER> (front) 

<TITLE_PAGE> 

<TITLE>(My Latest Book) 

<ORDER_NUMBER> (xx- 12345) 

<ABSTRACT> 

This book describes the latest changes to any product. 
<ENDABSTRACT> 

<REVISION_INFO>(Revision/Update Information:\This is a new manual. ) 
<ENDTITLE_PAGE> 

<COPYRIGHT_PAGE> 

<PRINT_DATE>(March 1987) 

<COPYRIGHT_DATE> (1987) 

<ENDCOPYRIGHT_PAGE> 

<PREF ACE> (11) 
<PREFACE_SECTION>(The changes to your system) 

<ENDPREF ACE> 

<ENDFRONT_MATTER> 


This example shows the order of all the front matter tags, and how they could 
be used in a file that contains the front matter of a book. 
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<GDEF> 


<GDEF> 


Begins the text that defines a term in a glossary. 





FORMAT 


<GDEF> (definition) 





ARGUMENTS 


related tags 


restrictions 


required 
terminator 


definition 
Specifies the definition of the term. 





® <GLOSSARY> 
e <GTERM> 


° <GREF> 





Can only be used between <GLOSSARY> and <ENDGLOSSARY> tags. 





None. 





DESCRIPTION See the description of the <GLOSSARY> tag. 





EXAMPLE 


See the example in the discussion of the <GLOSSARY> tag. 
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<GLOSSARY> 


<GLOSSARY> 


Formats a glossary of terms in a document or book. 





FORMAT <GLOSSARY > (text/ \ symbol-name]) 





ARGUMENTS text 
Specifies any text string that you want to label the start of the glossary. If no 
text is specified, the default text is the term “Glossary.” 


symbol-name 
Specifies the term that you assign to the glossary and then use to reference it. 


All symbol-names must not exceed 31 characters, and must only contain 
alphabetic letters, numbers, or underscores in them. Do not begin a symbol- 
name with an underscore. 








related tags *  <GTERM> 
° <GDEF> 
restrictions The symbol-name argument is required if this file will be included as part of 


a bookbuild. 


required <ENDGLOSSARY> 
terminator 


DESCRIPTION To create a glossary of terms, use the <GLOSSARY> tag to establish the 
eginning format. Follow this with a list of <GTERM> tags, with the glossary 
words defined as arguments to the <GTERM> tags. 


Typically, a definition of each glossary term follows the term itself. Create 
each definition with a <GDEF> (definition) tag. 


Remember to terminate the glossary with an <ENDGLOSSARY> tag. 





EXAMPLE 


<Glossary> 

<gterm> (habitat) 

<gdef>(An area or natural environment.) 
<gterm> (habitual) 

<gdef>(Acting according to habit.) 
<gterm> (hack) 

<gdef>(A worn-out horse.) 

<gterm> (hackneyed) 

<gdef>(Trite, banal.) 

<endglossary> 


This example produces the following output: 


<GLOSSARY> 


Glossary 


habitat: An area or natural environment. 
habitual: Acting according to habit. 
hack: A worn-out horse. 


hackneyed: Trite, banal. 
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<GREF> 


<GREF> 


Marks a cross-reference to a term within a glossary. 





FORMAT 


<GREF> (glossary-term) 





ARGUMENTS 


related tags 


restrictions 


required 
terminator 


glossary-term 
Specifies the term referred to. 





7 <GLOSSARY > 

° <GTERM> 

° <GDEF> 

¢ The following tags label other types of cross-references: 


<REFERENCE> 
<CALLOUT_REF> 





Invalid in math. 





None. 





DESCRIPTION The <GREF> tag marks a cross-reference to a term within a glossary. The 


glossary-term argument appears in an italic typeface in some document 
designs. 


<GTERM> 


<GTERM> 


Labels a term to be defined in a glossary. 





FORMAT 


<GTERM> (term) 





ARGUMENTS 


related tags 


restrictions 


required 
terminator 


term 
Specifies the term to be defined in the glossary. 





s <GLOSSARY> 
e <GDEF> 


bg <GREF> 





Can only be used between <GLOSSARY> and <ENDGLOSSARY> tags. 





<GDEF> 





DESCRIPTION The <GTERM> tag labels a term to be defined in a glossary. 





EXAMPLE 


See the example in the tag <GLOSSARY>. 
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<HEADx> 


<HEADx> 


Marks a heading of the level specified (1 through 6). 





FORMAT 


<HEADx> (heading-text [ \ symbol-name]) 





ARGUMENTS 


related tags 


restrictions 


required 
terminator 


heading-text 

Specifies the text of the heading. If the book design you are using produces 
headings that are all capital letters in your output, those letters will appear 
that way regardless of how you enter them in your input file. You should, 
however, use uppercase and lowercases letters according to your local 
conventions in order to obtain the proper capitalization of the heading in 
the table of contents and in cross-references. 


symbol-name 

The name of the symbol to be used in all references to this heading and the 
text following. Symbol-names must not exceed 31 characters, and must only 
contain alphabetic letters, numbers, or underscores in them. Do not begin a 
symbol-name with an underscore. 





. <SUBHEAD1> 


7 <SUBHEAD2> 


. <CHEAD> 





None. 





None. 


DESCRIPTION Each of the six tags, <HEADI>, <HEAD2>, <HEAD3>, and <HEAD4>, 
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<HEADS> , and <HEAD6> does the following: 


Outputs the heading text passed to it in its first argument 


Automatically numbers the heading 


Resets all of the counters for lower heading levels (if any) 


Specifies the symbol-name with which cross-references to that heading 
should be made 


Entries for each of the headings may appear in the table of contents, 
depending on the doctype design. 





EXAMPLES 
4] 


2 


<HEADx> 


The proper choice of the heading level depends on an understanding of the 
logical structure of the document you are writing. A <HEAD2> tag will 
always be logically subordinate toa <HEAD1> tag. The same is true for the 
relationship between <HEAD3> and <HEAD2>; <HEAD4> and <HEAD3> ; 
and so on. 


<HEAD1>(Running Tasks\tasks) 


This tag labels a first-level heading. 


<HEAD2>(SET and SHOW Commands\set_show_sec) 


This tag labels a second-level heading. 


You could make a cross reference to this heading by using the tag 
<REFERENCE> (set_show_-sec). In this example, if the heading was the 
second sublevel of the first section in the document, the reference would be 
output as Section 1.2. 


To control the output of the reference, use one of the formats listed in the 
following table: 


Reference Output 

<REFERENCE> (set_show_sec) Section 1.2 

<REFERENCE > (set_show_sec\value) 1.2 

<REFERENCE> (set_show_sec\text) Set and Show Commands 

<REFERENCE> (set_show_sec\full) Section 1.2, Set and Show 
Commands 
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<HELLIPSIS> 


<HELLIPSIS> 


Places horizontal ellipsis points on a line. 














FORMAT <HELLIPSIS> 
related tags e <ELLIPSIS> 
restrictions Invalid in math. 
required None. 

terminator 


DESCRIPTION The <HELLIPsis> tag places horizontal ellipsis points on a line. Often, it is 
used to label omitted material. 





EXAMPLE 


<P>A horizontal ellipsis may provide an indefinite ending <HELLIPSIS> 


This example may produce the following output: 


A horizontal ellipsis may provide an indefinite ending ... 
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<HYPHENATE> 


<HYPHENATE> 


Provides information about legal hyphenation of a word of text. 





FORMAT 


<HYPHENATE> (part? \ part2/ \ ...part9]) 





ARGUMENTS 


related tags 


restrictions 


part1...part9 

Specifies the word of text and its valid hyphenation points. Each argument 
to the tag specifies a portion of the word. Use the argument delimiter, the 
backslash, to indicate the hyphenation points. 





e <FINAL_CLEANUP> —LINE_BREAK 
e <LINE> 


° <KEEP> 





This tag is invalid in math and in monospaced examples. 





DESCRIPTION Use this tag when you are not satisfied with line breaks within paragraphs in 


your final output and you determine that the line breaks are caused because 
a word is not being hyphenated. This tag is also useful when a word or term 
(usually a technical term that is not commonly used) is not being hyphenated 
correctly. 


This tag does not force a term to be hyphenated; it merely provides the text 
formatter with information about legal places to break this occurrence of the 
word, should you need to break the word. 





EXAMPLE 


<p>Among the more common literary devices used by poets are 
<hyphenate>(on\o\mat\o\poe\ia) and anthropomorphism. 


The following shows the output this example may produce: 


Among the more common literary devices used by poets are onomato- 
poeia and anthropomorphism. 
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<ICON> 


<ICON> 


Allows you to include a graphic image in your printed output and print text 
parallel to the image. The text is printed either to the right or left of the 
picture. 





FORMAT <ICON> 





ARGUMENTS = None. 





related tags e  <FIGURE_FILE> 
e = <ICON_FILE> 


e <ICON_TEXT > 





restrictions Use the <ICON> tag for graphics that have a depth and width of 
approximately 2 inches. Use the <FIGURE_FILE> tag for larger graphics. 


The output device must be able to support graphics. 





required <ENDICON> 
terminator 





DESCRIPTION Use the <ICON> tag when you want to print a small graphic with 
explanatory text printed next to it. 





EXAMPLES 


<ICON> 

<ICON_FILE>(LNO3\small_art.six\1.5\2.O\RIGHT) 
<ICON_TEXT>(The text accompanying the 

small piece of art. The text can be smaller or larger 
than the graphic; the <tag>(ICON) tags make the necessary 
adjustments for the output.) 

<ENDICON> 


This example shows how to code a graphic on the right, with text on the left. 


<ICON> 


<ICON> 

<ICON_FILE>(LNO3\SANTA.SIX\15\11) 
<ICON_FILE>(LINE\Santa\3\8) 

<ICON_TEXT>(The image at the left is of an American icon. 
The personification of the spirit of Christmas, 

usually represented as a jolly, fat old man with 

a white beard and a red suit, is also called 
<quote>(Saint Nicholas) or <quote>(Saint Nick.)) 
<ENDICON> 

<ICON> 

<ICON_FILE>(LNO3\ELLIPSE. SIX\15\10\RIGHT) 
<ICON_FILE>(LINE\ellipse\3\8\RIGHT) 

<ICON_TEXT>(The image at the right is of an ellipse: 

a conic section taken neither parallel to an element nor parallel 
to the axis of the intersected cone. 

<ENDICON> 


This example shows one graphic placed on the left, with text on the right, 
followed by a second graphic placed on the right, with text on the left. The 
output appears as follows: 


The image at the left is of an American 
icon. The personification of the spirit of 
Christmas, usually represented as a jolly, fat 
old man with a white beard and a red suit, 
is also called “Saint Nicholas” or “Saint 
Nick.” 
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The image at the right is of an ellipse: a conic 
section taken neither parallel to an element 
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<ICON_FILE> 


<ICON_FILE> 


Specifies a graphics file that accompanies text within the <ICON> and 
<ENDICON> tags. 





FORMAT <ICON_FILE> (target-device 
\ file-spec 
\ vertical-size 
\ horizontal-size 
[ \ RIGHT) 





ARGUMENTS _target-device 
Specifies a keyword indicating the output device for the graphics file. 
Keywords are provided both for devices that do (LN03 and PS) and do 
not (LINE, MAIL, and TERMINAL) support graphics. Each keyword allows 
you to insert the necessary amount of white space for the specific output 
device; keywords for devices that do not support graphics allow you to insert 
blank space in place of an icon. The following table lists the output devices 
and expected output for each keyword. 


Keyword Device Output 
LNO3 LNO3 Laser Printer The specified sixel graphics file is 
Output as an icon. 
PS PRINTSERVER 40 or The specified POSTSCRIPT 
LNO3R SCRIPTPRINTER graphics file'is output as an 
icon. 
LINE Line Printer If specified, blank space is output 
MAIL with the file-spec argument 
TERMINAL written in that blank space. Only 


one of these three keywords 
should be used to indicate a 
monospaced destination. 


'PostScriet graphics files must conform to the Encapsulated PostScriet File Format 
published by Adobe Systems Incorporated. 


file-spec 
Specifies the graphics file. No default file type is supplied. 


vertical-size 

Specifies the vertical size of the printed graphic in picas (there are 6 picas to 
an inch). This argument may be a nonnegative integer or decimal number, 
including zero. 
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related tags 


restrictions 


required 
terminator 


<ICON_FILE> 


horizontal-size 

Specifies the width of the printed graphic in picas (there are 6 picas to an 
inch). This argument may be a nonnegative integer or decimal number, 
including zero. 


RIGHT 


Indicates that the graphic image is to be placed to the right of the text. If 
you do not specify this argument, the image is placed on the left of the text 
specified in the <ICON_TEXT> tag. 





. <FIGURE_FILE> 
* <ICON> 


. <ICON_ TEXT> 





You must have an output device that can print graphics files. 


Only valid when used between the <ICON> and <ENDICON> tags. 





None. 





DESCRIPTION 


Specifies a graphics file that accompanies text within the <ICON> and 
<ENDICON> tags. The specified file should be a graphics file suitable for 
printing on the specified output device. 


If you plan to process your file for more than a single destination, you can 
use multiple <ICON_FILE> tags to ensure that the appropriate icon will be 
included for the appropriate destination; an example of this coding is given 
in the examples in the <ICON> tag description. If you use multiple <ICON_ 
FILE> tags in this way, you should specify only a single <ICON_FILE> tag 
for all the monospaced destination keywords (MAIL, TERMINAL, or LINE). 





EXAMPLE 


See the examples in the <ICON> tag description. 
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<ICON_TEXT> 


<ICON_TEXT> 


Labels the text that accompanies a graphic image included in text with the 
<ICON> and <END_ICON> tags. 





FORMAT 


<ICON_TEXT> (text) 





ARGUMENTS 


related tags 


restrictions 


required 
terminator 


text 
Specifies the text that accompanies the graphic. It can be as long as you wish 
and can include paragraphs and lists. 





e <ICON> 


e <ICON_FILE> 





Must be used within the context of the <ICON> tag. 





None. 





DESCRIPTION The <ICON_TEXT> tag labels the text that accompanies a graphic image 


included in text with the <ICON> and <END_ICON> tags. 





EXAMPLE 


See the <ICON> tag description. 


<INCLUDE> 


<INCLUDE> 


Causes the contents of a specified file to be included in the current input 
file for processing. 





FORMAT <INCLUDE> (file-spec) 





ARGUMENTS _file-spec 
Specifies the file to be included. 


If a logical name is specified, instead, and the source file is an element of a 
book, you can define the logical name using an <INCLUDES_FILE> tag in the 
book’s profile. If the source file is not an element of a book, or if the profile 
does not contain the <INCLUDES_FILE> tag, be sure to define the logical 
name before processing the file through VAX DOCUMENT. 





related tags ¢ = <EXAMPLE_FILE> 
°  <TABLE_FILE> 





restrictions The <INCLUDE> tag is invalid in an argument to a tag. 


In a file that contains a book element to be processed through a bookbuild, 
make sure to place the book element tag (for example, <CHAPTER> ) as the 
first tag in the file. The <INCLUDE> tag should never be placed before the 
book element tag. 





required None. 
terminator 





DESCRIPTION The <INCLUDE> tag causes the contents of a specified file to be included in 
the current input file for processing. 





EXAMPLE 


<INCLUDE> (doc_local_templates : boilerplate .sdm1l) 
This example shows the inclusion of a file that does the following: 
e¢ Contains text that might be repeated multiple times in a source file 


e Is used in more than one document 
If the file specification doc_local_templates:boilerplate.sdml was not used, but 


instead substituted with a logical name, the logical name could be equated to 
the file specification by using the <INCLUDES_FILE> tag in the profile. 
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<INCLUDES_FILE> 


<INCLUDES_FILE> 


Equates a logical name with a file specification during processing of a 
profile. 





FORMAT 


<INCLUDES_FILE> (logical-name \ file-spec) 





ARGUMENTS 


related tags 


restrictions 


logical-name 
Specifies the logical name for the included file. You can use this name as the 
argument to an <INCLUDE> tag. 


file-spec 
Specifies the file specification into which the logical name translates. 





bd <PROFILE> 
s <ELEMENT> 


bd <INCLUDE> 





Must be used in the context of a profile. 








required None. 
terminator 
DESCRIPTION You can place the <INCLUDES_FILE> tag in your profile to define a logical 
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name for a file whose contents are included in one of your element files. 
The first argument to <INCLUDES_FILE> is the logical name for the included 
file. You use this name as the argument to the <INCLUDE> tag. The second 
argument specifies the actual file specification into which the logical name 
translates. 


The <INCLUDES_FILE> tags follow the <ELEMENT> tag for which they 

are needed. During a bookbuild, VAX DOCUMENT establishes the logical 
name definition for each <INCLUDES_FILE> tag before it actually reads and 
processes the book element file names in the preceding <ELEMENT> tag. The 
logical name remains defined during the processing of later book elements. 


When a book element is processed by itself (when you use the /PROFILE 
qualifier on the command line), VAX DOCUMENT again establishes the 
logical-name definitions that were specified by the <INCLUDES_FILE> tags in 
the profile. 


<INCLUDES_FILE> 





EXAMPLE 


<ELEMENT> (error_chap.SDML) 
<INCLUDES_FILE>(Error_msg_tab\Mydisk: [Mydirectory]my_very_long_table.sdm1) 


This example illustrates how the <INCLUDES_FILE> tag is used to define a 
logical name for a file (called “my—very—long_table.sdm1”) which is being 
kept in the directory [Mydirectory]. In the book element file ERROR— 
CHAP.SDML, the writer includes the table of error message codes with 
the tag: 


<include>(error_msg_tab). 
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<INDEX_FILE> 


<INDEX_FILE> 


Specifies the position in a book (or document) where an index file should 
be included in the output. 





FORMAT 


<INDEX_FILE> /(file-spec)] 





ARGUMENTS 


related tags 


restrictions 


required 
terminator 


file-spec 

If you place the <INDEX_FILE> tag in an SDML file that will be included 
in another file later, you must specify the exact file-spec of the index as the 
<INDEX_FILE> tag’s argument. 





° <PROFILE> 





None. 








DESCRIPTION 


The <INDEX_FILE> tag specifies the position in a source file where an index 
output file should be included. This tag does not produce an index, but 
simply indicates placement of the index file. An index file is produced when 
the qualifier “/INDEX” is specified on the DOCUMENT command line. 


The profile tags <INDEX—FILE> and <CONTENTS_FILE> can be placed in 
either the profile of a book or in a source file. If you are creating a book (with 
a profile to be processed through a bookbuild), place these tags in the profile 
to be sure of correct placement in the output. 


An index file always receives the filetype .DVI device, where device is 
the type of output device you specified on the command line. For more 
information on index generation, see Chapter 7. 


To create an index from an individual file that contains an <INDEX_FILE> 
tag, specify the “/INDEX” qualifier on the command line. 





EXAMPLE 


To see the result of the <INDEX_FILE> tag, refer to the index in this manual. 
The <INDEX_FILE> tag was placed in the profile file after the last appendix 
file. 


<INTERACTIVE> 


<INTERACTIVE> 


Begins an example dialog between user and system and enables the tags 
<S> and <U> to distinguish system text from user text. 








FORMAT <INTERACTIVE> (code) 
or 
[KEEP \ ] 
<INTERACTIVE> /( TWIDE| \ MAXIMUM] )] 
interactive code or text 
<ENDINTERACTIVE> 
ARGUMENTS code 


Specifies a code fragment you want to insert into your text. 


If this argument is not specified, the terminator <ENDINTERACTIVE> is 
required. 


KEEP 


Specifies that the example is not to be broken across pages, that is, if the 
example does not fit on the current page, it will be placed on the next page. 
If the example itself does not fit on a single page of output, it will be broken 
anyway. 


WIDE 


Specifies that the width of the example exceeds the document's default width 
for text. Depending on the document type, this argument can be interpreted 
as follows: 


e If the document style contains a left margin area that is normally used for 
headings, the example’s width will span that area as well as the normal 
text area. 


e If the document uses a multicolumn format, multicolumn output is 
suspended while the example is processed. The example is output and 
multicolumn output is then restored. 


e If the document style provides a range of sizes and styles for examples, 
this argument may be interpreted to mean that a specific size should be 
used for the example. 
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<INTERACTIVE> 


MAXIMUM 


Can be used in conjunction with WIDE to indicate that the example may 
require additional adjustment to fit within the bounds of the text page. 
This argument must be used with discretion, and may not be suitable in all 
document styles. 





related tags <S> 


<U> 


bd <VALID_BREAK> 





restrictions Indexing tags (<x> and <yY> tags) are not permitted within interactive 
examples. 


Tab characters cannot be used to format interactive examples; use spaces 
instead. 


Do not use text element tags within interactive examples (for example, <P>, 
<LIST> , or <NOTE> ). 





required <ENDINTERACTIVE> 
terminator 





DESCRIPTION The <INTERACTIVE> tag indicates the beginning of an example dialog 
between user and system. It enables the tags <S> and <U>. If your 
interactive example is longer than a few lines, use the <VALID_BREAK> tag to 
indicate the acceptable points for a page break within that example. 


EXAMPLE 


<P>If you do not specify the full command line, DCL will prompt 

you for the missing information. For example, if you do not specify an 
input file and an output file when you enter the COPY command, you will 
be prompted as follows: 


<INTERACTIVE> 
<S>($ )<U> (COPY) 

<S>($_From: ) <U> (INTERACT. GNC) 
<S>($_To: ) <U> (NEWFILE. GNC) 
<ENDINTERACTIVE> 


Note that you should specify whatever space follows the system prompt 
within the <S> tag. This example may produce the following output: 


If you do not specify the full command line, DCL will prompt you for the 
missing information. For example, if you do not specify an input file and an 
output file when you enter the COPY command, you will be prompted as 


follows: 
$ COPY 
$_From: INTERACT .GNC 
$_To: NEWFILE.GNC 


<KEEP> 


<KEEP> 


Specifies that a string of text should always occur on the same line of 
output. 





FORMAT <KEEP> (text) 





ARGUMENTS text 


Specifies the text string to be kept on the same line of output. 





related tags e The following tags are used in conjuction with <KEEP> to allow a user 
to specify formatting attributes: 


<EMPHASIS> 
<DEFINE_SYMBOL> 
<HYPHENATE> 








restrictions None. 
required None. 
terminator 





DESCRIPTION Specifies that a string of text should always occur on the same line of output; 
that is, it should not be broken between lines. The <KEEP> tag is used either 
to prevent hyphenation of a word or to prevent a string of text from breaking 
across a line. 





EXAMPLES 


<P> 
The complete file specification is: <KEEP>(DISK$: [SMITH. TRIPS .EXPENSES] MILEAGE. TXT) 


In this example, the file specification is specified as an argument to the keep 
tag so that it will not be broken across a line. This code fragment may 
produce the following output: 


The complete file specification is: 
DISK$:[SMITH.TRIPS.EXPENSESJMILEAGE.TXT 


LN) 


<define_symbol>(VAX11\<delayed><keep>(VAX--11)<enddelayed>) 


This defines a text element symbol-name using an en dash and specifies that 
the line should not break between the en dash and the 11 in the reference 
<REFERENCE> (vax11). 


A reference to this defined symbol would produce the following output: 


VAX-11 
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<KEYWORD> 


<KEYWORD> 


Labels a significant word that deserves to be distinguished typographically. 





FORMAT 


<KEYWORD> (word) 





ARGUMENTS 


related tags 


restrictions 


required 
terminator 


word 
Specifies the word to be distinguished. 





° <VARIABLE> 


. <SPECIAL_NAME> 





None. 





None. 





DESCRIPTION 


The <KEYWORD> tag labels a word or term that you want to distinguish 
typographically. The default action of the <KEYWORD> tag outputs the 
keyword in boldface. From the point of view of formatted result, the 
<KEYWORD> tag may appear similar to the <EMPHASIS> tag with the 
BOLD argument. However, by using separate tags to label different kinds of 
information, the book designer is free to change the format of any one kind 
without affecting the others. 


What constitutes a keyword is something about which both editor and writer 
must agree. The presence of keywords must be taken into account in the 
book design. Use of the <KEYWORD> tag should be consistent within a 
document and across a document set. 





EXAMPLE 


<P>A <KEYWORD>(field) is a set of contiguous bytes in a logical record. 
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This example may produce the following output: 


A field is a set of contiguous bytes in a logical record. 


<LE> 


<LE> 


Labels a list element. 





FORMAT 


<LE> [(callout-number)] 





ARGUMENTS 


related tags 
restrictions 


required 
terminator 


callout-number 

Used only within the context of <LIST> (CALLOUT) to set the callout 
number identifying the list element. See the examples in the discussion of 
<LIST> (CALLOUT). 





. <LIST> 





Must be used within the context of the <LIST> tag. 





None. 





DESCRIPTION The <LE> tag identifies a list element and is only valid when used within 


the context of the <LIST> tag. 





EXAMPLES 


See the examples in the discussion of the <LIST> tag. 


<LINE> 


<LINE> 


Specifies that the text that follows is to be placed on a new line of output. 





FORMAT INDENT \ unit-number] 
<LINE> /( | | BIGSKIP | )] 
SMALLSKIP 





ARGUMENTS INDENT 


Specifies that the next line or block of text is to be indented from the 
preceding text. If the INDENT argument is specified, the next argument 
must be an integer from 1 to 9 indicating the number of units that the text 
is to be indented. The size of these units is determined separately for each 
document design. 


The default indent is 1 unit; the maximum indent is 9 units. 


BIGSKIP 
SMALLSKIP 


Specifies that a set amount of vertical space is to precede the element 
identified as a line or block of text. The actual amount of space created is 
determined by the document’s design. 





related tags ¢ = <FINAL_CLEANUP> 
@ = <CENTER_LINE> 


e <RIGHT_LINE> 








restrictions Invalid in monospaced examples and math. 
required None. 
terminator 


DESCRIPTION The result produced by this tag differs according to whether it is used in the 
context of a <P> tag, a <TABLE_ROW> tag, or a <FORMAT> tag: 


When you specify <LINE> in the context of a paragraph of text or a list 
element, the <LINE> tag causes the current paragraph to be terminated 
and then starts a new block of text. By default, the text block is not 
preceded by any extra vertical space nor is it indented. 


When you specify the <LINE> tag in the context of a <TABLE_ROW> or 
a <FORMAT> tag, the <LINE> tag causes the next text to begin on a new 
line of output, but does not modify the current paragraph. 
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<LINE> 


Do not use the <LINE> tag in a paragraph to cause the text formatter to 
break a line within the paragraph. Breaking a line to override a specific 
line break is a final formatting/cleanup instruction and you should use the 
<FINAL_CLEANUP> (LINE_BREAK) tag for this. 





EXAMPLES 


—J «—- <LIST> (NUMBERED) 
<le>ITEM 
<LINE>This item specifies... 


The output may be formatted as follows: 


1 ITEM 
This item specifies .. . 


2 <P>This is a normal paragraph. 
<line> (INDENT\1\SMALLSKIP) 
This is a block paragraph, indented with skip. 


This may produce: 
This is a normal paragraph. 
This is a block paragraph, indented with skip. 


3} <P>Flashy designs are inappropriate for software manuals or for 
any serious or formal books because they do not reflect the 
intention of the writer. The purpose of any book design is 
<LINE> 
to clarify what the author is conveying, to translate the text 
attractively as print on a page, to communicate the message 
visually in harmony with the ideas. 


This output illustrates misuse of the <LINE> tag for formatting within a 
paragraph. Although correct results may be obtained.on a given output 
device for a particular run of a file, the output may also be formatted as 
follows: 


Flashy designs are inappropriate for software manuals or for any serious or 
formal books because they do not reflect the intention of the writer. The 
purpose of any book design is 


to clarify what the author is conveying, to translate the text attractively as 
print on a page, to communicate the message visually in harmony with the 
ideas. 
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<LINE> 


<TABLE>(Card Reader Errors: Causes and Corrective Actions\cardread_tab) 
<TABLE_ATTRIBUTES> (wide\multipage) 

<TABLE_SETUP> (3\12\21) 

<TABLE_HEADS>(Error\Causes\Corrective Action) 

<TABLE_ROW>(READ CHECK\Card edges torn <LINE> Punch in column 0 

or 81\Remove the faulty card from the output stacker, duplicate the card, place 
it in the input hopper, and press the <EMPHASIS>(RESET\bold) button.) 
<TABLE_ROW_BREAK> (FIRST) 

<TABLE_ROW>(PICK CHECK\Damage to leading edge <LINE> Torn webs 

<LINE> Cards 

stapled together\Remove the card from the input hopper, duplicate 

the faulty card, place the card back in the input 

hopper, and press the <EMPHASIS>(RESET\bold) button.) 
<TABLE_ROW_BREAK> (LAST) 

<TABLE_ROW>(STACK CHECK\Jam in the card track <LINE> Badly mutilated card 
\Correct the jam and/or remove the mutilated card from the output stacker, 
duplicate the card, place it in the input hopper, and press the 
<EMPHASIS>(RESET\bold) button. ) 

<TABLE_ROW> (HOPPER CHECK\Input hopper empty <LINE> Output stacker full\Load 
the input hopper. <LINE> Unload the output stacker. ) 

<ENDTABLE> 


This example shows the use of the <LINE> tag in a three-column table. It 
may produce the following output: 


Table x—-x Card Reader Errors: Causes and Corrective Actions 


Error Causes Corrective Action 
READ CHECK Card edges torn Remove the faulty card from the output stacker, 
Punch in column O or 81 duplicate the card, place it in the input hopper, and 
press the RESET button. 
PICK CHECK Damage to leading edge Remove the card from the input hopper, duplicate 
Torn webs: the faulty card, place the card back in the input 
Cards stapled together hopper, and press the RESET button. 
STACK CHECK Jam in the card track Correct the jam and/or remove the mutilated card 
Badly mutilated card from the output stacker, duplicate the card, place it 
in the input hopper, and press the RESET button. 
HOPPER CHECK Input hopper empty Load the input hopper. 


Output stacker full Unload the output stacker. 


<FORMAT> (MY COMMAND) 





<FCMD>( ) 
<FPARMS>(one parameter<line>two<line>three) 
<ENDFORMAT> 
This example shows the <LINE> tag in a <FORMAT> tag. This example may 
produce the following output: 
MY one parameter 


COMMAND two 


three 
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<LINE_ART> 


<LINE_ART> 


Labels a rough sketch produced at the terminal keyboard for draft output, 
to give some idea of what the final figure will look like. 





FORMAT 


[KEEP] 
SLINE—ART> [0 per, MAXIMUM]! 





ARGUMENTS 


related tags 


restrictions 


required 
terminator 


KEEP 

Specifies that the line art is not to be broken across pages, that is, if the line 
art does not fit on the current page, it will be placed on the next page. If the 
line art itself does not fit on a single page of output, it will be broken anyway. 


WIDE 


Specifies that the width of the line art exceeds the document's default width 
for text. Depending on the document type, this argument can be interpreted 
as follows: 


e If the document style contains a left margin area that is normally used for 
headings, the line art’s width will span that area as well as the normal 
text area. 


If the document uses a multicolumn format, the line art will result in 
suspension of multicolumn output while it is being processed. The line 
art will be output, and then multicolumn output will be restored. 


If the document style provides a range of sizes and styles for examples, 
this argument may be interpreted to mean that a specific size should be 
used for the line art. 


MAXIMUM 


Can be used in conjunction with WIDE to indicate that the line art might 
require additional adjustment to fit within the bounds of the text page. 
This argument must be used with discretion, and may not be suitable in all 
document styles. 





° <FIGURE> 


® <VALID_BREAK> 





None. 





<ENDLINE_ART> 
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<LINE_ART> 





DESCRIPTION The <LINE_arT> tag labels a rough sketch produced at the terminal 
keyboard for draft output, to give some idea of what the final figure will 
look like. 


Note that the results of keyboard drawing may be adequate for draft 
purposes, but will not be acceptable in the context of laser printer output. 


EXAMPLE See the examples in the discussion of the <FIGURE> tag. 
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“<LIST> 


<LIST> 


Begins a list. The type of list (for example, numbered or stacked) is 
specified by the argument to the <LIST> tag. 





FORMAT —<LLIST> (keyword \ attributes) 





ARGUMENTS KEYWORD 
Specifies the type of list. 


ALPHABETIC The list element identifiers are alphabetic letters. 

CALLOUT The list element identifiers are reverse-print callout numbers 
(on supported output devices), for example ©. 

NUMBERED | The list element identifiers are Arabic numerals. 

ROMAN The list element identifiers are Roman numerals. 

SIMPLE There are no list element identifiers. 

STACKED Individual list elements do not have identifiers, but the entire 


list is stacked within the specified set of delimiters (braces, 
brackets, double brackets, or single or double vertical rules.) 


UNNUMBERED List element identifiers are special characters. 


ATTRIBUTES 


Specifies the attributes of the list element identifiers. More than one attribute 


can be specified. 


Start-letter 


Uppercase 


Start-number 


BRACES 

BRACKETS 
DOUBLE_BRACKETS 
VERTICAL RULE 
DOUBLE_VERTICAL _RULE 


For an ALPHABETIC list. Specifies the alphabetic 
letter to use for the first item in the sequence. 
Subsequent items are automatically incremented. 


For an ALPHABETIC or ROMAN list. Specifies 
that the list element identifiers (alphabetic 

letters or Roman numerals) are to be printed 

in uppercase letters. By default, Alphabetic and 
Roman numeral list element identifiers are printed 
using lowercase letters. 


For a NUMBERED or ROMAN list. Specifies the 
number to be assigned to the first list element. 
Subsequent list elements are automatically 
incremented. 


For a STACKED list. Each attribute for a 
STACKED list specifies the delimiter to be used 
to surround the stacked elements. If no keyword 
is specified, list elements are stacked without a 
surrounding delimiter. 
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<LIST> 


related tags 


restrictions 


required 
terminator 


Char For an UNNUMBERED list. Specifies a single 
character or a tag that results in a single printed 
character of output that will be used to indicate 
list elements. If char is not specified, the bullet 
character is used. 





cd <LE> 





The <LIST> tag should only used in the context of a paragraph or table. 


<LIST> tags that use the following keywords may be nested (that is, 

an element of a list may itself contain the beginning of another list): 
ALPHABETIC, NUMBERED, UNNUMBERED, ROMAN, or SIMPLE. 
However, none of these list types are compatible with <LIST> (STACKED). 
Stacked lists may only be nested within other stacked lists, and stacked lists 
may not be nested within any of the previously noted lists. 





<ENDLIST> 





DESCRIPTION 


The <LIST> (ALPHABETIC), <LIST> (NUMBERED), and <LIST> (ROMAN) 
tags begin a list whose elements have a particular sequence or priority. Use 
the UNNUMBERED or SIMPLE arguments to begin a list that has no inherent 
order or priority. 


Alphabetic lists are useful nested within numbered lists. A numbered list is 
used to indicate a particular sequence or priority within the list elements. 


The SIMPLE argument labels a simple list with no enumerator or special 
character preceding each list element. 


The STACKED argument begins a list whose elements are left-justified 

on successive lines of an imaginary box. The box can have large braces 

or brackets placed on each side. The box is then centered vertically so 

that it aligns with text to the left or right on the same line. (By contrast, 
<LIST> (SIMPLE) terminates the current paragraph and indents the list, 

so that it is seen as a separate entity from the text above and below it.) 
<LIST> (STACKED) is especially useful for showing syntactic elements with a 
<FORMAT> tag. 


The UNNUMBERED argument labels lists that have no particular order or 
priority within the list element. Normally a bullet is the character used before 
each list element. You can specify another character by passing it as an 
argument. 





EXAMPLES 


f] = <LIST> (NUMBERED) 
<LE>Review doc plan 


<LE>Find out these numbers: 
<LIST> (UNNUMBERED) 


<LE>LPN 
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<LIST> 


<LE>DPN 
<LE>order number 
<ENDLIST> 
<LE>For revisions of books not already in the library, have 
production or the writer rename the file 
according to its new LPN. 
<LE>Open a library for the book if none exists (except for 
one-shot jobs). 
<LIST> (ALPHABETIC) 
<LE>Decide with writer about timing: 
<LIST> (UNNUMBERED) 
<LE>Must be done before final production. 
<LE>Shouldn't be done until text is stable. 
<LE>Preferred time is at major edit pass. 
<ENDLIST> 
<LE>Cooperate with production librarian on paperwork. 
<LE>Help writers name new element files correctly. 
<LE>Verify that all files are of the same file type. 
<LE>For a revision, be sure files are renamed using the 
revision's LPN when the library is created for the revision. 
<ENDLIST> 
<ENDLIST> 


In this example, the first nested list has no particular sequence. The second 
nested list does have an order to it and this order is reflected in the use of the 
<LIST> (alphabetic) tag. 


This example may produce the following output: 
1 Review doc plan 
2 Find out these numbers: 

e LPN 

¢ DPN 

¢ order number 


3 For revisions of books not already in the library, have production or the 
writer rename the file according to its new LPN. 


4 Open a library for the book if none exists (except for one-shot jobs). 
a. Decide with writer about timing: 
¢ Must be done before final production. 
¢ Shouldn’t be done until text is stable. 
e Preferred time is at major edit pass. 
b. Cooperate with production librarian on paperwork. 
c. Help writers name new element files correctly. 
d. Verify that all files are of the same file type. 


e. For a revision, be sure files are renamed using the revision’s LPN 
when the library is created for the revision. 
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<LIST> 


FJ = <p>Items e and f describe the $GETJPI AST activity: 
<LIST> (ALPHABETIC\S) 
<LE>An ACB is constructed for a special kernel AST. 
<LE>When the special kernel mode AST routine executes in the context of 
the target process, the requested information is moved into the system buffer. 
The ACB is then reset to deliver a special kernel mode AST back to the 
requesting process. 
<ENDLIST> 


This example may produce the following output: 
Items e and f describe the $GETJPI AST activity: 
e. An ACB is constructed for a special kernel AST. 


f. When the special kernel mode AST routine executes in the context of the 
target process, the requested information is moved into the system buffer. 
The ACB is then reset to deliver a special kernel mode AST back to the 
requesting process. 


3} <P>At this point, you can log in to the system as the system manager 
by performing the following steps at the console terminal: 
<LIST> (NUMBERED) 
<LE>Press RETURN. 
<LE>In response to the system's request for your user name, type SYSTEM. 
<LE>In response to the system's request for your password, type MANAGER. 


<ENDLIST> 
This example produces the following output: 
At this point, you can log in to the system as the system manager by 
performing the following steps at the console terminal: 
1 Press RETURN. 
2 In response to the system’s request for your user name, type SYSTEM. 
3 In response to the system’s request for your password, type MANAGER. 

4 <P>Items six and seven describe two main principles of a generic 

markup language: 

<LIST> (NUMBERED \6) 

<LE>Descriptive markup predominates and is distinguished from processing 

instructions. 

<LE>Markup is formally defined for each type of document. 

<ENDLIST> 


This example has the following output: 


Items six and seven describe two main principles of a generic markup 
language: 


6 Descriptive markup predominates and is distinguished from processing 
instructions. 


7 Markup is formally defined for each type of document. 
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5) <P>The following items are needed: 

<LIST> (SIMPLE) 

<LE>bread 

<LE>milk 

<LE>cheese 

<LE>cereal 

<LE>fruit 

<ENDLIST> 


This example produces the following output: 


The following items are needed: 


bread 
milk 
cheese 
cereal 
fruit 


Gg <P> 


ON <LIST>(stacked\braces) 
<LE>ANYCONDITION 
<LE>ENDFILE (reference) 
<LE>ENDPAGE (ref erence) 
<LE>FINISH 
<LE>KEY (reference) 
<LE>UNDEF INEDFILE (reference) 
<LE>ERROR 
<LE>F IXEDOVERF LOW 
<LE>OVERFLOW 
<LE>UNDERFLOW 
<LE>VAXCONDITION (expression) 
<LE>ZERODIVIDE 

<ENDLIST> 


<LIST>(stacked\braces) 
<LE>statement 
<LE>begin-block 
<ENDLIST> 


<LIST> 


Notice that the tags are indented to help in visually checking the matching of 
the <LIST> (stacked) and <ENDLIST> tags. This indentation has no effect on 


the output, however. This example may produce the following: 


ANYCONDITION 
ENDFILE(reference) 
ENDPAGE(reference) 
FINISH 
KEY(reference) 


on J UNDEFINEDFILE(reference) { need 7 
egin-bloc 


ERROR 

FIXEDOVERFLOW 
OVERFLOW 

UNDERFLOW 
VAXCONDITION(expression) 
ZERODIVIDE 
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<LIST> 


<P> 
OPEN FILE (reference) [TITLE(expression) ] 
<P> 
<LIST>(stacked\brackets) 
<LE>[STREAM] <LIST>(stacked\brackets) 
<LE> [INPUT] 
<LE>OUTPUT [LINESIZE] [PRINT [PAGESIZE(integer)] ] 
<ENDLIST> 
<LE>RECORD <LIST>(stacked\brackets) 
<LE> [INPUT] 
<LE>OUTPUT 
<LE>UPDATE 
<ENDLIST> 
<LIST>(stacked\brackets) 
<LE>DIRECT 
<LE> [SEQ [UENTIAL] ] 
<ENDLIST> 
[KEYED] 
<ENDLIST> 


This example may produce the following: 


OPEN FILE (reference) [TITLE(expression)] 


[INPUT] 
ia! | OUTPUT [LINESIZE] [PRINT [PAGESIZE(integer)] ] 


INPUT] | DIRECT 


[ 
OUTPUT 
GpGATE [SEQ(UENTIAL]] 


RECORD [KEYED] 








<TABLE> 
<TABLE_SETUP> (2\20) 
<TABLE_HEADS> (Some stacked\Stuff in a Table) 
<TABLE_ROW> (<LIST> (stacked\braces) 
<LE>one 
<LE>two 
<LE>three 
<ENDLIST>\That was stacked in a table.) 
<TABLE_ROW>(Just a second item\<LIST>(stacked\braces) 
<LE>one 
<LE>two 
<LE>three 
<ENDLIST>) 
<TABLE_ROW>(this is the last item) 
<ENDTABLE> 


Here, <LIST> (stacked) arguments are used within a table. Again, the generic 
code is indented simply as an aid for visually checking the nesting of tags. 
This example may produce the following: 


Some stacked Stuff in a Table 
one That was stacked in a table. 
two 
three 
Just a second item one 
two 
three 


this is the last item 
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<LIST> 


<P>To create a system that more closely suits the requirements of 

your site, you can do any of the following: 

<LIST> (UNNUMBERED) 

<LE>Select a default bootstrap command procedure 

<LE>Modify system parameters for special hardware configuration needs or 
special workload requirements 

<LE>Perform other site-specific modifications 

<ENDLIST> 


This example may produce the following output: 


To create a system that more closely suits the requirements of your site, you 
can do any of the following: 


e Select a default bootstrap command procedure 


e Modify system parameters for special hardware configuration needs or 
special workload requirements 


e Perform other site-specific modifications 


<P>To create a system that more closely suits the requirements of 

your site, you can do any of the following: 

<LIST> (UNNUMBERED \ +) 

<LE>Select a default bootstrap command procedure 

<LE>Modify system parameters for special hardware configuration needs or 
special workload requirements 

<LE>Perform other site-specific modifications 

<ENDLIST> 


This example shows how you can specify a character other than.a bullet to 
label each list element. This example may produce the following output: 


To create a system that more closely suits the requirements of your site, you 
can do any of the following: 


+ Select a default bootstrap command procedure 


+ Modify system parameters for special hardware configuration needs or 
special workload requirements 


+ Perform other site-specific modifications 
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<LITERAL> 


<LITERAL> 


Allows you to specify text that contains words in angle brackets that 
might otherwise be interpreted as tags. 





FORMAT <LITERAL> (literal-text) 
or 


<LITERAL> 
literal-text 


<ENDLITERAL> 





ARGUMENTS _/iteral-text 


The literal text to be passed through the tag translator unprocessed. 














related tags None. 

restrictions None. 

required <ENDLITERAL> Required if the text is not specified as an argument. 
terminator 

EXAMPLE 


<P> I've experimented with my own method for noting questionable 
phrases, by placing <LITERAL><NOTE_PROBLEM><ENDLITERAL> near the 
phrase. 


This example may have the following output: 


I’ve experimented with my own method for noting questionable phrases, by 
placing <NOTE_PROBLEM> near the phrase. 
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<LOWERCASE> 


<LOWERCASE> 


Labels text that should appear as lowercase in the final output. 





FORMAT <LOWERCASE> (text) 





ARGUMENTS _ text 


Specifies the text to appear in lowercase. 











related tags ¢  <UPPERCASE> 
restrictions None. 

required None. 
terminator 





DESCRIPTION In your book, there may be a text element, such as a heading, that normally 
appears in uppercase. For example, in some book designs, first-level headings 
use all uppercase letters. 


You may encounter a situation where you need to overcome the default case 
in one of your tags and ensure that the result in the final output appears in 
lowercase. The <LOWERCASE> tag allows you to do this. 





EXAMPLE 


<HEAD2>(HeRe iS aN ExAmP1E oF <LOWERCASE>(10wErCaSe) tExT) 


In this example, assume that the doctype being used causes the tag <HEAD2> 
to output a heading that is in uppercase, no matter what the case of the text 
passed to it. 


The example may produce the following output: 
HERE IS AN EXAMPLE OF lowercase TEXT 


The default to uppercase letters causes the heading to be uniformly MpPercaee) 
with the exception of the text passed to the <LOWERCASE> tag. 
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<MARK> 


<MARK> 


Indicates the beginning of new or modified information. 





FORMAT 


<MARK> 





ARGUMENTS 


related tags 


restrictions 


required 
terminator 


None. 





7 <REVISION> 


® <UPDATE_RANGE> 





Output is enabled only if the <REVISION> tag has been specified. 





<ENDMARK> 





DESCRIPTION The <MARK> and <ENDMARK> tags delimit a sequence of text that has 


been modified. These tags will produce vertical bars in the margin of the 
document. 


Make sure to place the <MARK> and <ENDMARK> tags next to the text 
they mark, without preceding or following the text with other tags. The text 
formatter interprets <MARK> based on the last text character encountered 
before the <MARK> tag. 





EXAMPLE 


<P> 


The following characters are legal in MACRO-11 source programs: 


<LIST> (UNNUMBERED) 


<LE>The letters A through Z. Both upper- and lowercase letters are 
acceptable, although, upon input, lowercase letters are converted to 


uppercase. 


<LE>The digits O through 9. 


<LE>The characters period <PARENDCHAR>(.) and dollar sign 
<PARENDCHAR>($). These characters are reserved for use as Digital 
Equipment Corporation system program symbols. 


<ENDLIST> 


<MARK> 


<REVISION> 


<P> 

The following characters are legal in MACRO-11 source programs: 
<LIST> (UNNUMBERED) 

<LE>The letters A through Z. Both upper- and lowercase letters are 
acceptable, although, upon input, lowercase letters are converted to 
uppercase. 


<MARK> 

<LE>Characters in the DEC multinational character set (MCS). A chart 
showing the MCS is located in <REFERENCE>(mcs_app) , 

with a list of directives that 

support the MCS. 

<ENDMARK> 


<LE>The digits O through 9. 

<LE>The characters period <PARENDCHAR>(.) and dollar sign 
<PARENDCHAR>($). These characters are reserved for use as Digital 
“Equipment Corporation system program symbols. 

<ENDLIST> 


In this example, the first paragraph is the original and the second paragraph 
is the modified version with the <MARK> and <ENDMARK> tags coded in. 
The formatted output for the original paragraph and the modified paragraph 
may be as follows: 


The following characters are legal in MACRO-11 source programs: 


e The letters A through Z. Both upper- and lowercase letters are acceptable, 
although, upon input, lowercase letters are converted to uppercase. 


¢ The digits 0 through 9. 


e The characters period (.) and dollar sign ($). These characters are 
reserved for use as Digital Equipment Corporation system program 
symbols. 


The following characters are legal in MACRO-11 source programs: 


e The letters A through Z. Both upper- and lowercase letters are acceptable, 
although, upon input, lowercase letters are converted to uppercase. 


e Characters in the DEC multinational character set (MCS). A chart showing 
the MCS is located in Appendix A, with a list of directives that support 
the MCS. 


e = The digits 0 through 9. 


e The characters period (.) and dollar sign ($). These characters are 
reserved for use as Digital Equipment Corporation system program 
symbols. 
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<MATH> 


<MATH> 


Labels a short mathematical expression or the beginning of an extended 
mathematical example. 








FORMAT math-expression 
a (| DISPLAY/ \ symbol-name] \ 
ARGUMENTS math-expression 


related tags 


restrictions 


required 
terminator 
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Specifies a mathematical expression to be included in the text of a sentence or 
paragraph. 


DISPLAY 


Specifies a keyword indicating that an extended mathematical equation or 
expression is to be set off from the surrounding text. 


symbol-name 

Specifies a symbol-name by which the extended mathematical equation is to 
be referenced. If this argument is specified, the equation is assigned a number 
and the number is printed to the right of the equation. 


Symbol-names must not exceed 31 characters, and must only contain 
alphabetic letters, numbers, or underscores in them. Do not begin a symbol- 
name with an underscore. 


Once the symbol-name is defined, the equation can be referenced using the 
<REFERENCE> tag. 





° <MATH_CHAR> 
° <CODE_EXAMPLE> 


bd <REFERENCE> 





e The use of extended mathematical examples is not valid within tables or 
monospaced examples. 


¢ The set of tags valid within a mathematical expression is limited to those 
listed in the tables in the following “Description” section. 





<ENDMATH> —Required when DISPLAY is specified as an argument to 
<MATH> . 


<MATH> 





DESCRIPTION 


Note: 


Within an argument to <MATH> or within the bounds of 

<MATH> (DISPLAY) ... <ENDMATH> , you can specify simple or complex 
mathematical expressions, according to the rules outlined below. The context 
in which you enter text and tags within a mathematical expression is severely 
restricted. 


In a mathematical expression, all formatting is controlled by the text 
processor. When you use the keyword DISPLAY, the output will be 
offset from the surrounding text, but you do not have any control over its 
positioning. Furthermore, blank spaces and carriage returns are ignored; 
the text processing program assumes that all text strings are mathematical 
variable names, and makes all decisions regarding the output formatting. 


Simple Expressions 


The following tags are used to indicate simple binary operations. In the 
context of a mathematical expression, you can use either the tag name or the 
function’s symbol. 


<TIMES> * Multiplication 
<PLUS> + Plus 
<MINUS> - Minus 
<DIVIDED_BY > / Division 
<EQUALS> = Equality 


For example, the following are equivalent: 


<MATH> (total = A+B-Cx*D/ £) 
<MATH>(total <EQUALS> A <PLUS> B <MINUS> C <TIMES> D <DIVIDED_BY> E£) 


Both produce the output: total = A+ B—C* D/E 


The use of any nonalphanumeric characters other than those specified 
above in the context of math may produce unpredictable results, including 
errors from the text formatter. 


Operators are evaluated using the normal mathematical rules for precedence 
of operators. You can control the evaluation by using the <GROUP> tag, 
much as you would use parentheses in a mathematical expression. Note the 
use of the <GROUP> tag in the second math expression in the following code 
fragment: 

<MATH> (total = A +B-C*D<OVER>(e) ) 

<P> 

<MATH> (total = <GROUP>(<GROUP>(A +B-C*D)<OVER>(e)) ) 


This code fragment may produce the following output: 
total=A+B—C*D 
e 


— A+B-CxD 
total = eo 


The effect of the <GROUP> tag is supplied by default for fractional 
expressions when you use the <FRACTION> tag: 


<MATH> (display) 


total = <FRACTION>(A + B - C * D\E) 
<ENDMATH> 
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<MATH> 


Variable Names 


The text formatter assumes that variable names are primarily alphabetic letters 
or special characters represented by the <MATH_CHAR> tag. If you need to 
specify any variable names in expressions that contain special characters, you 
must use the <VARIABLE> or <TEXT> tags. For example: 


<MATH> (<variable>(event_flag) = 1) 
If you require multiword variable names, you must use the <SP> tag to 
indicate spacing: 


<MATH> (display) 
<VARIABLE> (SUCCESS<sp>RATE) <equals> 
<group>( 
<VARIABLE>(TOTAL<SP>HITS) <over>(<VARIABLE>(TOTAL<sp>HITS) <plus> 
<VARIABLE>(TOTAL<sp> MISSES) 
) 

) 
<times> 100 
<ENDMATH> 


This example may produce the following output: 


TOTAL HITS 


TOTAL HITS + TOTAL MISSES * 1 


SUCCESS RATE = 


You can provide special annotation for variable names by using the following 
tags: 


Tag Output 
<BAR_CHAR> (x) 
<DOT_CHAR> (x) 
<HAT> (xyz) 
<HAT_CHAR> (x) 
<OVERLINE> (var) 
<TILDE> (xyz) 
<TILDE_CHAR> (x) 
<UNDERLINE> (var) 
<VECTOR> (x) 


& <) & &I 
id 
R 


ar 


)g 


8 
< 
Xx 


ec & 


Ql | 


Parentheses 


Most of the tags valid in math do not accept arguments. However, 
parentheses are frequently used in mathematical expressions. You must 
be careful, therefore, to use spaces preceding the parentheses. For example: 


<MATH>(A <minus> (B<PLUS>C) ) 
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Summary of Tags 


<MATH> 


Table 9-3 summarizes the tags that are valid in mathematical expressions. 


Table 9-3 <MATH> Expressions 


Tag 
<AMPERSAND> 


<ATOP> (expression) 
<BACKSLASH> 


<CAL> (letter) 


<CASES> 
<CASE_ROW > 
<ENDCASES> 


<CDOTS> 
<CHOOSE> (expression 1\expression2) 
<DDOTS> 


<DIVIDED_BY > 

<DOTS> 

<DOT_TIMES > 

<EQUALS> 

<FRACTION> (numerator \denominatorn 
<FUNC> (expression) 

<GROUP> (expression) 


<INTEGRAL> 


<INTEGRAL _LIMITS> 


<INTEGRAL_NOLIMITS> 


<MATRIX> 
<MATRIX_ROW > 
<ENDMATRIX> 


<MINUS> 
<MOD> 


Operation and Output 
Specifies a literal ampersand 
character in a math expression. 
Stacks an expression, as in >. 


Specifies a literal backslash character 
in a math expression. 


Specifies a calligraphic uppercase 
letter, as in A. 


Specifies a case construction. See 
“Matrices and Cases.” 


Specifies centered dots, as in ---. 
Parenthetical notation, as in (¢). 


Specifies diagonal dots, as in °. 
Division, as in a/b. 

Specifies horizontal dots, as in.... 
Multiplication, as in a- b. 

Equality, as in a = b. 

Specifies a fraction, as in ¢. 
Specifies a function, as in f(a). 


Provides control over the order of 
operation. See “Examples,” in the 
following section. 


Specifies an integral, as in [,*. See 
“Operators With and Without Limits.” 


Specifies an integral that places 
superscripts and subscripts above 
and below the sign, rather than to 
the right. See “Operators With and 
Without Limits.” . 


Specifies an integral that places 
superscripts and subscripts to the 
right of the sign, rather than above 
and below. See “Operators With and 
Without Limits.” 


Specifies a matrix. See “Matrices and 
Cases.” 


Minus, as in a — b. 


Modulo, as in n mod p. 
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Table 9—3 (Cont.) 


Tag 


<LBAR> 


<LBRACE> 


<LBRACKET > 


<LCEIL> 


<LFLOOR> 


<LPAREN> 


<OVER> (expression) 
<PI> 

<PLUS> 

<PMOD> (expression) 
<PROD> 


<PROD_LIMITS> 


<PROD_NOLIMITS> 


<RBAR> 


<RBRACE > 


<RBRACKET > 


<MATH> Expressions 


Operation and Output 


Begins an expression delimited 
with vertical bars. See “Delimited 
Expressions.” 


Begins an expression delimited 
with curly braces. See “Delimited 
Expressions.” 


Begins an expression delimited with 
square brackets. See “Delimited 
Expressions.” 


Begins an expression delimited with 
ceil characters ({). See “Delimited 
Expressions.” 


Begins an expression delimited with 
floor characters (|). See “Delimited 
Expressions.” 


Begins an expression delimited 
with parentheses. See “Delimited 
Expressions.” 


Division, as in ¢. 

The pi character, 7. 

Plus, as ina+ b. 

Parenthetical mod, as ina (mod p). 


Specifies a product, as in Tz . See 
“Operators With and Without Limits.” 


Specifies a product that places 
superscripts and subscripts above 
and below the sign, rather than to 
the right. See “Operators With and 
Without Limits.” 


Specifies a product that places 
superscripts and subscripts to the 
right of the sign, rather than above 
and below. See “Operators With and 
Without Limits.” 


Ends an expression delimited 
with vertical bars. See “Delimited 
Expressions.” 


Ends an expression delimited 
with curly braces. See “Delimited 
Expressions.” 


Ends an expression delimited with 
square brackets. See “Delimited 
Expressions.” 


<MATH> 


Table 9-3 (Cont.) <MATH> Expressions 


Tag 


<RCEIL> 
<RFLOOR> 
<RPAREN> 


<SP> 


<SQRT> (expression) 
<SUBSCRIPT > (expression) 
<SUM> 


<SUM_LIMITS> 


<SUM_NOLIMITS> 


<SUPERSCRIPT> (expression) 


<TEXT> 
<TIMES> 
<TO> 
<VARIABLE> 


<VDOTS> 


<VECTOR> (var) 
<X_TIMES> 


Operation and Output 


Ends an expression delimited with 
ceiling characters (|). See “Delimited 
Expressions.” 


Ends an expression delimited with 
floor characters (|). See “Delimited 
Expressions.” 


Ends an expression delimited 
with parentheses. See “Delimited 
Expressions.” 


Provides space in a variable name or 
expression. 


The square root, as in //a. 
Subscription, as in ap. 


Specifies summation, as in a }_ b. 
See “Operators With and Without 
Limits.” 

Specifies summation that places 
superscripts and subscripts above 
and below the sign, rather than to 
the right. See “Operators With and 
Without Limits.” 


Specifies summation that places 
superscripts and subscripts to the 
right of the sign, rather than above 
and below. See “Operators With and 
Without Limits.” 


Exponentiation, as in a’. See 
“Operators With and Without Limits.” 


Specifies text in a math expression. 
Multiplication, as in a * b. 
Indicates progression, as in 1 — 10. 


Specifies a variable name that 
contains nonalphanumeric characters. 


Specifies vertical dots, as in «. 
A vector, as in Z. 
Multiplication, as in a x b. 
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Operators With and Without Limits 


When you specify <SUBSCRIPT> and <SUPERSCRIPT> tags, the superscription 
or subscription applies to the immediately preceding variable or expression. 
These tags can be specified in any order, as shown in the following code 
fragment: 


<MATH> (a<subscript>(2)<superscript>(n-1)) 

: : 2 _n-l 
This code fragment may produce the following output: a, 
In extended mathematical expressions, the <SUPERSCRIPT> and 
<SUBSCRIPT> tags produce differing results in conjunction with the 
<INTEGRAL> , <PROD>, and <SUM> functions and their complementary 
tags <INTEGRAL_LIMITS> and <INTEGRAL_NOLIMITS> , <PROD_LIMITS> and 
<PROD_NOLIMITS> , and <SUM_LIMITS> and <SUM_NOLIMITS> . 


The <INTEGRAL>, <PROD>,and <SUM> tags place their subscripts and 
superscripts depending on whether the tags are used in math text mode (used 
as an argument to the <MATH> tag) or in math display mode (used between 
the <MATH> (DISPLAY) and <ENDMATH> tags). 


In math text mode, the <INTEGRAL>, <PROD> and <SUM> tags all place 
the superscript and subscript to the right. These tags are coded as follows: 


<MATH> (<integral><subscript>(n=1)<superscript>( <pi><over>(2) ) <sp>  ) 
<MATH> ( <prod><subscript>(n=1)<superscript>( <pi><over>(2) ) <sp> ) 
<math> ( <sum><subscript> (n=1)<superscript>( <pi><over>(2) ) ) 


This code fragment may have the following output: 
fof yt 
n=1 n=1 n=1 


In math display mode, the <PROD> and <SUM> tags place the superscript 
and subscript above and below their respective signs; however, the 
<INTEGRAL> tag places superscripts and subscripts to the right. These 
tags are coded as follows: 


<MATH> (display) 

<integral><subscript>(n=1)<superscript>( <pi><over>(2) ) <sp> 
<prod><subscript>(n=1)<superscript>( <pi><over>(2) ) <sp> 
<sum><subscript>(n=1)<superscript>( <pi><over>(2) ) 

<ENDMATH> 


This code fragment may have the following output: 


us 
T Le 


iis 


n=1 n=1 


The <INTEGRAL_NOLIMITS> , <PROD_NOLIMITS> , and <SUM_NOLIMITS> 
tags always place the subscripts and superscripts to the right of the signs, 
regardless of the math mode. These tags are coded as follows: 


<MATH> (display) 

<integral_nolimits><subscript>(n=1)<superscript>( <pi><over>(2) ) <sp> 
<prod_nolimits><subscript>(n=1)<superscript>( <pi><over>(2) ) <sp> 
<sum_nolimits><subscript>(n=1)<superscript>( <pi><over>(2) ) 

<ENDMATH> 


<MATH> 


This code fragment may have the following output: 


x 
Te 
n=1 n=1 n=1 


The <INTEGRAL_LIMITS> , <PROD_LIMITS> , and <SUM_LIMITS> tags always 
place the subscripts and superscripts above and below the signs, regardless of 
the math mode. These tags are coded as follows: 


<MATH> (display) 
<integral_limits><subscript>(n=1)<superscript>( <pi><over>(2) ) <sp> 
<prod_limits><subscript>(n=1)<superscript>( <pi><over>(2) ) <sp> 
<sum_limits><subscript>(n=1)<superscript>( <pi><over>(2) ) 
<ENDMATH> 


This code fragment may have the following output: 


Mathematical Functions 


In addition to the operations and special functions listed in Table 9-3, you 
can specify mathematical functions using any of the tags listed in Table 9-4. 
These tags all let you specify the tag with or without an argument. If you 
specify an argument, it is placed in parentheses following the function name. 
For example: | 


<MATH> (<SIN>(d)) 


This produces: sin(d). 


Table 9—4 Tags for Mathematical Functions 


Tag Function 
<ARCCOS> arccos 
<ARCSIN> arcsin 
<ARCTAN> arctan 
<ARG> arg 
<COS> cos 
<COSH> cosh 
<COT> cot 
<COTH> coth 
<CSC> csc 
<DEG> deg 
<DET> det 
<DIM> dim 
<EXP> exp 
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Table 9—4 (Cont.) Tags for Mathematical Functions 








Tag Function 
<GCD> gcd 
<HOM> hom 
<INF> inf 
<KER> ker 
<LG> lg 
<LIM> lim 
<LIMINF > lim inf 
<LIMSUP> lim sup 
<LN> In 
<LOG> log 
<MAX> max 
<MIN> min 
<MOD> mod 
<PMOD> (mod n) 
<PR> Pr 
<SEC> sec 
<SIN> sin 
<SINH> sinh 
<SUP> sup 
<TAN> tan 
<TANH> tanh 





For example, the following: 


<LIST> (UNNUMBERED) 


<le><math> ( 
<sin>2<math_char>(theta) 
<equals>2<sin><math_char> (theta) <cos><math_char> (theta) 


~~ 


<le><math> ( 
O(n <log>n <log><log>n) 


<le><math> ( 
<pr>(X >x)= <exp>(-x/<math_char>(mu) ) 


<le><math> ( 
<max><subscript> (1<math_char>(geq)n<math_char>(geq)m) 
<log><subscript> (2) P<subscript> (n) 


~~ 


<le><math> ( 

<lim><subscript> (x<to>0) <group> ( 
<sin>x<over>(x)) 

<equals>1 

) 

<ENDLIST> 
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Produce: 
e = sin 20 = 2sin @ cos 8 
e O(nlog nlog log n) 
e = Pr(X > 2) = exp(—2/p) 
© =MaX1>n>m 082 Pn 
sin z 


. lim,_.9 =e 1 


Delimited Expressions 


To produce delimited expressions in mathematics, you must use one of the 
following pairs of tags: 


e¢ <LBAR> and <RBAR> —for opening and closing vertical bars 
e¢ <LBRACE> and <RBRACE> —for opening and closing curly braces 


¢ <LBRACKET> and <RBRACKET> —for opening and closing square 
brackets 


e¢ <LCEIL> and <RCEIL> —for opening and closing ceiling delimiters 


<LFLOOR> and <RFLOOR> —for opening and closing floor delimiters 


¢ <LPAREN> and <RPAREN> —for opening and closing parentheses. 


The text formatter automatically assumes that text within these pairs is to be 
grouped, and it sizes the delimiters automatically. 


For example: 


<MATH> (display) 
<group>( 
C<subscript> (dg) 


<fraction>(<math_char>(partial)Q<subscript>(d) \ 
<math_char> (partial) V<subscript> (g) ) 


-C<subscript> (oxt) 
{0.5 
+ 


<lparen>f<subscript>(0) DVG - 
<group>(2f<subscript>(0) V<subscript> (com) <over>(f<subscript>(1)) 


<rparen> 
<group>(1 <over>(f<subscript>(1)<superscript>(2))) 


<ENDMATH> 


This produces: 


_ OQ4 _ 2foVcom 1 
Cag — Vy — —Cozt [os + (sve — een 5 
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Matrices and Cases 


You can construct matrices and case constructs using the tags provided with 
<MATRIX> and <CASES>. 


The <MATRIX> tag has the format: 


BRACES 
<MATRIX> ( | BRACKETS ) 
VERTICAL RULE 


Where the keywords BRACES, BRACKETS, and VERTICAL—RULE override 
the default matrix delimiter, parentheses. 


When you construct a matrix, each row in the matrix must be specified using 
the <MATRIX_ROW> tag. You can specify a maximum of nine columns for 
the row. The matrix must be terminated with the <ENDMATRIX> tag. For 
example: 


<matrix> (brackets) 
<matrix_row>(A) 
<matrix_row>(B) 
<matrix_row>(C) 
<matrix_row>(D) 
<endmatrix> 


This simple, one-column matrix may produce the following output: 


VQAwe 


A more complex example shows how to code a multi-column matrix: 


<math> (display) 
<det><matrix>(vertical_rule) 
<matrix_row>(c<subscript>(0) \c<subscript>(1)\ 
c<subscript>(2) \<dots>\c<subscript>(n)) 
<matrix_row>(c<subscript>(1)\c<subscript>(2)\ 
c<subscript>(3)\<dots>\c<subscript>(n+1)) 
<matrix_row>(c<subscript>(2) \c<subscript> (3) \ 
c<subscript> (4) \<dots>\c<subscript>(n+2) ) 
<matrix_row>(<vdots>\<vdots>\<vdots>\<vdots>) 
<matrix_row>(c<subscript>(n) \c<subscript>(nt+1)\ 
c<subscript>(n+2) \<dots>\c<subscript>(2n) ) 
<endmatrix> > 0. 


<endmath> 
Would produce: 
Co Cy C2 se Cn 
Cy C2 C3 aie Cn+1 
c2 C3 C4 ites Cn+2 
det > 0. 
Cn Cn+t Cn+2 +++ Cdn 


<MATH> 


<CASES> is similar to <MATRIX> , but it produces only a large left-hand 
brace; there is no closing delimiter. It is specified as: 


<MATH> (display) 

<cases> 
<case_row>(1/3\if\0> x\;) 
<case_row>(2/3\if\3< x\;) 
<case_row>(0O\elsewhere. ) 


<endcases> 

<ENDMATH> 

This might produce: 
1/3 ifO0> <a; 
2/3 if 3<4a; 


0 elsewhere. 





EXAMPLES 


The circumference of a circle is calculated using the 
formula <MATH>(c<equals><pi>r<superscript>(2)). 


This example illustrates a simple mathematical expression used in the text of a 
sentence. This example produces: “ The circumference of a circle is calculated 
using the formula c = r?.” 


<MATH> (DISPLAY) 
vsize <equals> psize <minus>(<minus>topglue) <minus> topdepth <minus> footerglue 
<ENDMATH> 
This example produces: 
vsize = psize — (—topglue) — topdepth — footerglue 
Note that the parenthetical expression following the first <MINUS> tag must 
have a space in front of it; otherwise the expression will be interpreted as an 
argument to <MINUS>. 
<LIST> (NUMBERED) 


<le><MATH> (1<over>(2)) 

<le><MATH> (n+1<over> (3) ) 

<le><MATH> (<choose>(N+1\3)) 

<le><MATH> (<sum><subscript>(n=1)<superscript> (3) Z<subscript>(n)<superscript>(2) ) 
<ENDLIST> 


This list of simple inline expressions produces: 


14 
2 8 
3 ("3") 
4 ne Zh 
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<MATH> (DISPLAY) 
<GROUP> ( 
a<over>(x<plus>y<superscript>(3) ) 


<EQUALS> <SQRT>(<times><pi>) 
<ENDMATH> 


This example illustrates how to use the <GROUP> tag to indicate the order 
of operation. Its output is: ‘ 
= f/*7 


z+y? 





Note what the output would be if the <GROUP> tag is not present: 


a 


z+ y? = Vt 
<MATH>(total = A+B-C¥#*D// E) 


In this example, the characters representing the mathematical operations are 
used directly. The output is: total = A+ B-—C*D/E. Note that this is 
equivalent to: 


<MATH> (total <EQUALS> A <PLUS> B <MINUS> C <TIMES> D <DIVIDED_BY> £) 
<MATH>(--)This begins a comment line. 


This example illustrates how to use the <MATH> tag to generate true minus 
signs in your SDML files. This example results in: 


——This begins a comment line. 


<MATH> (DISPLAY\widget_equation) 

widgets = crickets + bats 

<ENDMATH> 

<p>As <REFERENCE>(widget_equation) shows, the relationship between 
bats and widgets must include crickets. 


This example shows how you may use the <REFERENCE> tag to refer to an 
equation. This example may produce the following output: 


widgets = crickets + bats (9-1) 


As (9-1) shows, the relationship between bats and widgets must include 
crickets. 
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<MATH_—CHAR> 


Creates a special mathematical symbol. 





FORMAT 


<MATH_CHAR> (keyword) 





ARGUMENTS 


related tags 


restrictions 


required 
terminator 


keyword 
A keyword indicating the special symbol you want to access. The keywords, 
and the symbols they produce, are listed in Table 9-5. 





¢ | <MATH> —provides tags for operations in constructing mathematical 
expressions. 


¢ | <MCS>-—provides access to special characters available in the DEC 
Multinational Character Set. 


° <SPECIAL__CHAR> 





¢ The <MATH_CHAR> tag is invalid in the monospaced example tags. 


The characters produced using <MATH_CHAR> are sized only for normal 
text sizes and therefore will not produce good visual results in header 
levels, text in the OVERHEADS doctype, and so on. 





None. 





DESCRIPTION Table 9-5 summarizes the keywords and special symbols you can access with 
th 


e <MATH_CHAR> tag. 


Table 9-5 <MATH_—CHAR> Symbols 


Keyword Symbol 
The Greek Letters 
ALPHA 

BETA 

GAMMA 

DELTA 

EPSILON 
VAREPSILON 
ZETA 

ETA 

THETA 


Re Si. “ay 3p 


Sa 3° 
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Table 9-5 (Cont.) <MATH—CHAR> Symbols 


Keyword Symbol 
The Greek Letters 


VARTHETA 0 
lOTA 
KAPPA 
LAMBDA 
MU 

NU 

Xl 
OMICRON 
P| 

VARPI 
RHO 
VARRHO 
SIGMA 
VARSIGMA 
TAU 
UPSILON 
PHI 
VARPHI 
CHI 

PSI 
OMEGA 


~ 


oS mir} a 


79 9 B PB Qa 


ge €& x 6 © C¢ 


The Uppercase Greek Letters 
UPPERCASE_ALPHA 
UPPERCASE_BETA 
UPPERCASE_GAMMA 
UPPERCASE_DELTA 
UPPERCASE_EPSILON 
UPPERCASE_ZETA 
UPPERCASE_ETA 
UPPERCASE_THETA 
UPPERCASE_IOTA 
UPPERCASE_KAPPA 
UPPERCASE_LAMBDA 
UPPERCASE_MU 
UPPERCASE _NU 
UPPERCASE _XI 


nm 2zZzern-OotNe pA wD 
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Table 9-5 (Cont.) <MATH_CHAR> Symbols 


Keyword Symbol 
The Uppercase Greek Letters 


UPPERCASE_OMICRON 
UPPERCASE_PI 
UPPERCASE_RHO 
UPPERCASE_SIGMA 
UPPERCASE _TAU 
UPPERCASE_UPSILON 
UPPERCASE_PHI 
UPPERCASE _CHI 
UPPERCASE _PSI 
UPPERCASE_OMEGA 


De @R uD O 


The Ordinal Operators 
ALEPH 
ANGLE 
BACKSLASH 
BOT 
CLUBSUIT 
DIAMONDSUIT 
DOUBLE_VERT 
ELL 
EMPTYSET 
EXISTS 
FLAT 
FORALL 
HBAR 
HEARTSUIT 
IMATH 
IM 
INFTY 
JMATH 
NABLA 
NATURAL 
NEG 
PARTIAL 
PRIME / 
RE 
SHARP 


a a 


gQrityru SA 


> (ane, < ihe I 


~ 8 
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Table 9—5 (Cont.) <MATH—CHAR> Symbols 


Keyword Symbol 
The Ordinal Operators 
SPADESUIT 

SURD 

TOP 

TRIANGLE 

WP 


S pPoHA< 


Binary Operators 
AMALG 

AST 

BIGCIRC 
BIGTRIANGLEDOWN 
BIGTRIANGLEUP 
BULLET 

CAP 

CDOT 

CIRC 

CUP 

DAGGER 
DDAGGER 
DIAMOND 

DIV 

MP 

ODOT 

OMINUS 

OPLUS 

OSLASH 
OTIMES 


= 


© “bx CO -* 


a) 


o + + C Oo 


® O88 OOH 
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Keyword 
Binary Operators 


PM 

SETMINUS 
SQCAP 

SQCUP 

STAR 

TIMES 
TRIANGLELEFT 
TRIANGLERIGHT 
UPLUS 

VEE 

WEDGE 

WR 


<MATH—CHAR> 


<MATH_CHAR> Symbols 
Symbol 


> < € VA x * EC JD“ # 


~ 
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Table 9—5 (Cont.) <MATH—WCHAR> Symbols 


-Keyword . Symbol 
Relational Operators 
APPROX 
ASYMP 
BOWTIE 
CONG 
DASHV 
DOTEQ 
EQUIV 
FROWN 
GEO > 
GG > 
IN € 
LL < 
LEQ 
MID 
MODELS 
NI 
NOTSUBSETEQ 
NOT_APPROX 
NOT_ASYMP 
NOT_CONG 
NOT_EQUIV 
NOT_EQ 
NOT_GEQ 


it 


I; + R X 


) 


MWK THOR KH BR MN VT 7 IA 
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Keyword 
Relational Operators 


NOT_GT 
NOT_LEO 
NOT_LT 
NOT_PRECEQ 
NOT_PREC 
NOT_SIMEO 
NOT_SIM 
NOT_SOQSUBSETEQ 
NOT_SQSUPSETEQ 
NOT_SUBSET 
NOT_SUCCEQ 
NOT_SUCC 
NOT_SUPSETEQ 
NOT_SUPSET 
PARALLEL 
PERP 

PRECEO 

PREC 

PROPTO 
SIMEQ — 

SIM 

SMILE 
SQSUBSETEQ 
SOSUPSETEO 
SUBSETEQO 
SUBSET 
SUCCEQ 
SUCC 
SUPSETEQ 
SUPSET 
VDASH 


<MATH_CHAR> 


<MATH—CHAR> Symbols 
Symbol 


oh y* YK AHS NH RRARKRAM XM 


R A IA FE 


I 


TUW YW A IN WIN ¢ 
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Table 9—5 (Cont.) <MATH—CHAR> Symbols 


Keyword Symbol 
Arrows 
DOUBLE__DOWNARROW 
DOUBLE _LEFT ARROW 
DOUBLE _LEFTRIGHT ARROW 
DOUBLE_LONGLEFT ARROW 
DOUBLE _LONGLEFTRIGHT ARROW 
DOUBLE —LONGRIGHT ARROW 
DOUBLE _RIGHT ARROW 
DOUBLE _UPARROW 
DOUBLE __UPDOWNARROW 
DOWNARROW 

HOOKLEFT ARROW 
HOOKRIGHT ARROW 
LEFTARROW 
LEFTHARPOONDOWN 
LEFTHARPOONUP 
LEFTRIGHT ARROW 
LONGLEFT ARROW 
LONGLEFTRIGHT ARROW 
LONGMAPSTO 

LONGRIGHT ARROW 
MAPSTO 

NEARROW 

NW ARROW 

RIGHT ARROW 
RIGHTHARPOONDOWN 
RIGHTHARPOONUP 
RIGHTLEFTHARPOONS 
SEARROW 

SW ARROW 

UPARROW 
UPDOWNARROW 


Se Nee de ob ge eek | el | fee ak tp ate if Sees AD | f ft tt 
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Table 9-5 (Cont.) <MATH—CHAR> Symbols 


Keyword Symbol 
Delimiters 
LANGLE 
RANGLE 
LBRACE 
RBRACE 
LBRACK 
RBRACK 
LCEIL 
RCEIL 
LFLOOR 
RFLOOR 


See ee 


ee 
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<MCS> 








FORMAT <MCS> (character) 

ARGUMENTS character 
Specifies the character referred to. The character may be any one of the 
following: 
Argument Character Decimal Value 
spanish_inverted_exclamation 161 . 
cents ¢ 162 
british_pound £ 163 
—_ [reserved] 164 
japanese_yen ¥ 165 
— [reserved] 166 
section_sign § 167 
general_currency ® 168 
copyright © 169 
feminine_ordinal a 170 
double_open_angle_brackets « 171 
— [reserved] 172 
— [reserved] 173 
— [reserved] 174 
—_— [reserved] 175 
degree ui 176 
plus_or_minus Ba 177 
superscript2 2 178 
superscript3 3 179 
—_— [reserved] 180 
micro ” 181 
pilcrow q 182 
raised_period ° 183 
—_ [reserved] 184 
superscript 1 : 185 
masculine_ordinal fe] 186 
double_close_angle_brackets » 187 
one_fourth %s 188 
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Labels a character in the DEC Multinational Character Set. 


Argument 


one_half 
spanish_inverted_question 
cap_a_grave 
cap_a_acute 
cap_a_circumflex 
cap—a_tilde 
cap_a_umlaut 
cap_a_ring 
cap_ae 
cap_c_cedilla 
cap_e_grave 
cap_e_acute 
cap__e_circumflex 
cap__e_umlaut 
cap_i_grave 
cap__i_acute 
cap_i_circumflex 
cap_i_umliaut 
cap__n_tilde 
cap_o_grave 
cap_o_acute 
cap__o_circumflex 
cap_o_tilde 
cap__o__umlaut 
cap_.oe 
cap—o_slash 
cap_u_grave 
cap__u_acute 
cap_u_—circumflex 
cap__u_umlaut 
cap_y—umlaut 
german_ss 
small_a_grave 
small_a_acute 
small_a_circumflex 


small_a_tilde 


Character 
Vp 


[reserved] 


= — sm: Som Som IT 6 By po DP: D>: > >. > 


[reserved] 


<cOoCcCAQRQR OOOO Oo 2 


[reserved] 


oO ww DW 


o> 


a 


<MCcs> 


Decimal Value 


189 
190 
191 
192 
193 
194 
195 
196 
197 
198 
199 
200 
201 
202 
203 
204 
205 
206 
207 
208 
209 
210 
211 
212 
213 
214 
215 
216 
217 
218 
219 
220 
221 
222 
223 
224 
225 
226 
227 
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~ <MCS> 


related tags 


restrictions 


required 
terminator 





DESCRIPTION The <Mcs> tag labels a character in the DEC Multinational Character Set. 
Note that this tag is required only when the input device (terminal) you are 
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Argument 


small_a_umlaut 
small_a_ring 
small_ae 
small_c_cedilla 
small_e_grave 
small_e_acute 
small_e_circumflex 
small_e_umlaut 
small_i_grave 
small_i_acute 
small_i_circumflex 
small_i_umlaut 
small_n_tilde 
small_o_grave 
small_o_acute 
smaill__o_circumflex 


- small_o_tilde 


small_o_umlaut 
small_oe 
small_o_slash 
small_u_grave 
small_u—acute 
small_u_—circumflex 
small_u—umlaut 
smali_y—umlaut 





bd <MATH—CHAR> 


° <SPECIAL__CHAR> 





Invalid in math. 





None. 


Character 


OM DM 6O 8 Qe Q: 


@M: @® 


—_— 


—\ 


[reserved] 


< oc Ooo & &@ GR OF OF oO oO & 3B 


[reserved] 


Decimal Value 
228 
229 
230 
231 
232 
233 
234 
235 
236 
237 
238 
239 
240 
241 
242 
243 
244 
245 
246 
247 
248 
249 
250 
251 
252 
253 
254 


using does not accept or display these special characters. 


<MCS> 





EXAMPLE 


<P>The DEC Multinational Character Set includes the currency sign 
for the Japanese yen (<MCS>(japanese_yen)). 


This example may produce the following output: 


The DEC Multinational Character Set includes the currency sign for the 
Japanese yen (¥). 
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<NESTED_TABLE_BREAK> 


> 


<NESTED_TABLE_BREAK> 


Marks a place that a nested table may be broken across pages. 





FORMAT 


<NESTED_TABLE_BREAK> 





ARGUMENTS 


related tags 


restrictions 


required 
terminator 


None. 





bd <TABLE> 


<TABLE_FILE> 


<TABLE_SPACE> 


<REFERENCE> 





The <NESTED_TABLE_BREAK> tag must be used within a nested table, that 
is, a table begun within a table row. Also, breakpoints for long tables nested 
inside multipage tables have the following limitations: 


e §6©The first level table must not use the KEEP attribute. 


e The first level table must be set up with only two or three columns. 





None. 





DESCRIPTION 
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The <NESTED_TABLE_BREAK> tag marks a place that a nested table may be 
broken across pages. A nested table is a table that is coded within another 

table. You create a nested table by placing the appropriate table tags within 
an argument to the <TABLE_ROW> tag of the outer table. See the Example 
section in this tag description for an example of this coding. 


If you place a <NESTED_TABLE_BREAK> tag in a nested table that contains 
headings, the headings are not repeated on subsequent pages. Also, a rule 
may be output at the point that the tag is included, thereby appearing to end 
the nested table which continues on the next page. 


<NESTED_TABLE_BREAK> 





EXAMPLE 


<TABLE>(Table Caption\tab_log_name) 
<TABLE_SETUP>(2\10) 

<TABLE_HEADS>(First Head\Second Head) 
<TABLE_ROW>(Item Here\Definition for Item here.) 


<TABLE_ROW>(Item Here\Definition that tells about 
<COMMENT>(*nested table begins*) 


<TABLE> 

<TABLE_SETUP> (2\15) 

<TABLE_ROW>(Item\Text of item description 
<TABLE_ROW>(Item\Text of item description 


<TABLE_ROW>(Item\Text of item description 
<TABLE_ROW>(Item\Text of item description 
<NESTED_TABLE_BREAK> 

<TABLE_ROW>(Item\Text of item description 


<TABLE_ROW>(Item\Text of item description 
<NESTED_TABLE_BREAK> 
<TABLE_ROW>(Item\Text of item description 


<TABLE_ROW>(Item\Text of item description 


<TABLE_ROW>(Item Here\Definition for Item 
<TABLE_ROW>(Item Here\Definition for Item 
<ENDTABLE> 


<COMMENT>(*nested table ends*) 
) 
<TABLE_ROW>(Item Here\Definition for Item here.) 
<TABLE_ROW>(Item Here\Definition for Item here.) 
<TABLE_ROW>(Item Here\Definition for Item here.) 
<ENDTABLE> 


nested table. 


here) 
here) 


here) 
here) 


here) 


here) 


here) 


here) 


here. ) 
here.) 


This example illustrates the coding of the <NESTED_TABLE_BREAK> tag. 
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<NEWTERM> 


<NEWTERM> 


Labels a term first introduced into the text in order to emphasize the term. 





FORMAT 


<NEWTERM> (term) 





ARGUMENTS 


related tags 


term 
Specifies the word just introduced. 





° <KEYWORD> 


. <VARIABLE> 














restrictions Invalid in math. 

required None. 

terminator 

DESCRIPTION The <NEWTERM> tag labels a term first introduced into the text in order to 
emphasize the term. In output, the term will be italicized. 

EXAMPLE 


<P>To begin a session at the terminal, you must first <NEWTERM>(log in). 
Logging in consists of getting the system's attention and identifying yourself as 


an authorized user. 
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This example may produce the following output: 


To begin a session at the terminal, you must first log in. Logging in consists 
of getting the system’s attention and identifying yourself as an authorized 
user. 


<NOTE> 


<NOTE> 


Labels a note, caution, warning, or some other portion of text to which 
you wish to draw attention. 





FORMAT <NOTE> [(heading-text)] 
note-text 


<ENDNOTE> 





ARGUMENTS _heading-text 


Specifies text for a heading other than the default heading “Note:”. 











note-text 
Specifies the text of the note. A paragraph is implied here, sono <P> tag is 
needed. 

related tags None. 

restrictions None. 

required <ENDNOTE> 


terminator 





DESCRIPTION The <NOTE> tag labels a note, caution, warning, or some other portion of 
text to which you wish to draw attention. A note will be formatted differently 
depending on the doctype specified on the DOCUMENT command line. 





EXAMPLE 


<NOTE>(Caution) You should abort the system generation command 
procedure only after Phase 1 has completed processing. 
<ENDNOTE> 


This example might produce the following output, depending on the doctype 
specified: 


Caution: You should abort the system generation command procedure only after . 
Phase 1 has completed processing. 
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<OPAREN> 


<OPAREN> 


Supplies an unmatched opening parenthesis in an argument to a tag. 





FORMAT <OPAREN> 





ARGUMENTS = None. 





related tags ¢ The following tags label other characters that must be tagged when they 
occur in an argument to a global tag: 


<AMPERSAND> 
<BACKSLASH > 
<CPAREN> 
<VBAR> 








restrictions None. 
required None. 
terminator 


DESCRIPTION The <OPAREN> tag can be used anywhere to insert an open parenthesis 
character into text. However, it is only beneficial (in terms of keystrokes and 
control of the output) as an unmatched opening parenthesis in an argument 
passed to a tag. 


An unmatched parenthesis in an argument can cause errors when processed 
because the parentheses are used to determine the beginning and ending 
of an argument list. The <OPAREN> tag inserts the opened parenthesis 
character but is not evaluated as an opened parenthesis. 





EXAMPLE 


<SUBHEAD1>(Using an Opened Parenthesis <PARENDCHAR>(<OPAREN>) in an Argument to a Tag) 


This example may produce the following output: 


Using an Opened Parenthesis (() in an Argument to a Tag 


<ORDER_NUMBER> 


<ORDER_NUMBER> 


Labels the order number or part number that may appear on the title page 
of a book. 





FORMAT <ORDER_NUMBER> (number) 





ARGUMENTS number 


Specifies the order number for the book. 











related tags None. 

restrictions The <ORDER_NUMBER> tag is valid only within a title page. 
required None. 

terminator 





DESCRIPTION The <ORDER_NUMBER> tag labels the order number or part number that may 
appear on the title page of a book. 





EXAMPLE See the example in the <FRONT_MATTER> discussion. 


N 
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<P> 


Marks the beginning of a new paragraph. 





FORMAT <P> 





ARGUMENTS = None. 





related tags ° <CP> 
e <LINE> 


s <CENTER—LINE> 


° <RIGHT_LINE> 








restrictions None. 
required None. 
terminator 





DESCRIPTION The <P> tag marks a new paragraph of text. An internal counter keeps track 
of the context in which the new paragraph begins, so that you can freely use 
<P> tags inside lists and in other contexts where you want to start a new 
paragraph, while maintaining the same logical level of discussion. 


A <P> tag is expected after every heading. If you do not immediately start a 
new paragraph after a heading, you must label the beginning of another text 
element, such as a list. 





EXAMPLES 


<P> 

Here is a sentence or two in a paragraph. The following paragraph 

will show the <TAG>(P) tag at work separating paragraphs. 

<P>Here is the second paragraph so that you can observe the relationship 
it has to the first. 


This example may produce the following output, depending on the doctype 
specified: 


Here is a sentence or two in a paragraph. The following paragraph will show 
the <P> tag at work separating paragraphs. 


Here is the second paragraph so that you can observe the relationship it has 
to the first. 
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<P> 


2 <list> (unnumbered) 
<le>Oranges 
<le>Apples 
<p>Note that there are several types of apples<hellipsis> 
<le>Bananas 
<endlist> 


This example shows how a paragraph can be used within a list. This example 
may produce the following output: 


e Oranges 
e = Apples 
Note that there are several types of apples ... 


e Bananas 
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<PAGE> 


<PAGE> 


Breaks a page of text, forcing the text that follows the tag to begin on a 
new page. 








FORMAT EVEN 
<PAGE> 
2 a ODD } 
ARGUMENTS EVEN 
ODD 


related tags 


restrictions 


required 
terminator 


Specifies whether the new page of output should have an even or an odd 
page number. 


Note that if you use one of these arguments, you might have two consecutive 
pages of output numbered such as 13 or 15. There will be no blank page of 
output between the pages. 





¢ <FINAL_CLEANUP> —page—break 





The arguments EVEN and ODD are invalid in tables. 


Invalid in math. 





None. 





DESCRIPTION The <PAGE> tag breaks a page of text, forcing the text that follows the tag to 


begin on a new page. 


Note: Use this tag only in special cases, where a page must be broken at that 
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point. This tag is not for general use, such as for overall pagination; 
this can jeopardize the output format and device independence of your 
generically coded source file. 


<PAGE> 





EXAMPLE 


<HEAD1>(Survey Results) 


<PAGE> 
<HEAD2>(Brand X) 


<PAGE> 
<HEAD2>(Brand Z) 


This example shows the coding of a short document in which the information 
might be easier to index when specific headings start on new pages. 


9-179 


<PARENDCHAR> 


<PARENDCHAR> 


Labels a character that will appear alone within parentheses to achieve 
better spacing. 





FORMAT 


<PARENDCHAR > (char) 





ARGUMENTS 


related tags 


char 
Specifies the character within parentheses. Specify only the character. The 
parentheses will be added during processing. 





None. 








restrictions Invalid in math. 

required None. 

terminator 

DESCRIPTION Frequently writers use the name for a special character followed by that 
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character in parentheses. For instance, in discussing wildcard characters it is 
natural to say, “The percent sign (%) is the wildcard for a single character.” 


A problem in using proportionally spaced fonts is that single characters 
surrounded by parentheses can look quite crowded, like this: “The percent 
sign (%) is the wildcard for a single character.” (Compare the percent sign 
in parentheses in this paragraph to the percent sign in parentheses in the 
previous paragraph; you can see the slight crowding at the top left corner of 
the percent sign.) 


Typographers put a small amount of space, called a “thin space,” between the 
parentheses and the single character to achieve a balance. When you use the 
<PARENDCHAR> tag, that thin space is added for you. 


You should use the <PARENDCHAR> tag to label characters that are small or 
that are more vertical than horizontal in shape. 


When using the <PARENDCHAR> tag, do not enter the parentheses that will 
surround the character. The parentheses will be added during processing. 


<PARENDCHAR> 





EXAMPLE 


<P>The tilde <PARENDCHAR>(~) is used to prevent the word 
following it from becoming a main entry in the index. 


This example may produce the following output: 


The tilde (~ ) is used to prevent the word following it from becoming a main 
entry in the index. 


Without the <PARENDCHAR> tag, your output would look like this: 


The tilde (~) is used to prevent the word following it from becoming a main 
entry in the index. 
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<PART> 


<PART> 


Labels the start of a major division within a document, and starts it on a 
new page. 

















FORMAT <PART> [(zone-title \ symbol-name)] 

ARGUMENTS zone-title 
Specifies the title for this part of your document. 
symbol-name 
Specifies the term that you assign to this part and then use to reference the 
part throughout your document. The symbol-name argument is required only 
if the part will be included in a bookbuild. 
Symbol-names must not exceed 31 characters, and must only contain 
alphabetic letters, numbers, or underscores in them. Do not begin a symbol- 
name with an underscore. 

restrictions None. 

required None 

terminator 

DESCRIPTION A document may be logically divided into units called “Parts,” which may 


consist of the following: 
¢ A set of chapters or appendixes whose contents are logically related. 


e A collection of units of logically related information, for example, 
reference items in the SOFTWARE doctype. 


The <PART> tag begins a new part and optionally assigns a title to it. Like 
chapters, parts are automatically numbered. If you specify a symbol-name 
argument, a symbol table entry is created for the part. 


The <PART_PAGE> tag creates a divider page for a part and optionally 
provides an abstract describing information in the part. 


By default, the part page is assigned the next odd page number in the 
current numbering sequence in a document that does not have chapters. 
If RENUMBER is specified in the <ENDPART_PAGE> tag, the part page 
is assigned the page number of 1, and the next printed page of output is 
numbered page 3. 


<PART> 





EXAMPLES 


<part>(Reference Information\ref_part) 

<part_page> 

<title>(<reference>(ref_part) \<reference>(ref_part\text) ) 
<abstract> 

This part contains reference chapters. <reference>(intro_part) 
contains tutorial information. 

<endabstract> 

<endpart_page> 


This example shows how to code the tags <PART> and <PART_PAGE>, 
assigning a zone-title and a symbol-name to a part. 


<part>(Introduction\intro_part) 

<part_page> 

<title>(<reference>(intro_part) \<reference>(intro_part\text) ) 
<abstract> 

This part contains introductory chapters. <reference>(ref_part) 
contains more detailed reference information. 

<endabstract> 

<endpart_page> 


This example results in the following if this is the first part specified in the 
document. 


e Asymbol table entry for the symbol-name intro_part, whose value is 1 
and whose text is “Introduction.” 


e The <PART_PAGE> tag creates a new page of output. The page is 
assigned the next odd page number in the numbering sequence. 


e The title: “PART I Introduction’ will be printed at the top of the page. 
The use of uppercase roman numerals to display the part number is a 
document-type-specific design attribute. 


e¢ The abstract text is printed. 
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<PART_PAGE> 


<PART_PAGE> 


Begins a divider page for a new part of a document. 





FORMAT <PART_PAGE> 





ARGUMENTS = None. 





related tags ¢  <TITLE> 
. © <RUNNING_TITLE> 


° <ABSTRACT> 








restrictions None. 
required <ENDPART_PAGE> 
terminator 





DESCRIPTION The <PART> tag divides a document into one of its major constituent parts. 
The <PART_PAGE> tag (together with <ENDPART_PAGE> ) simply inserts an 
extra page in between major sections. 


By labeling a part page, you also define three related tags: <TITLE>, 
<ABSTRACT> , and <RUNNING_TITLE>. You can use these related tags to 
put either a title or an abstract on the page (or both), and you can determine 
the running title for the text that follows the part page as well. 





EXAMPLE 


<PART_PAGE> 

<TITLE>(Part II) 

<ABSTRACT> 

Part II provides reference information on each global tag in SDML. 
<ENDABSTRACT> 

<RUNNING_TITLE>(Descriptions of Global Tags) 

<ENDPART_PAGE> 


This example illustrates the use of both the <PART_PAGE> and <ENDPART_ 
PAGE> tags, and the related tags that can be used to put a title on the page, 
print a brief abstract, and set the running title for the text that follows. 
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<PREFACE> 


<PREFACE> 


Labels the beginning of a preface. 





FORMAT 


<PREFACE> /(page-number)] 





ARGUMENTS 


related tags 
restrictions 


required 
terminator 


page-number 

Specifies the page number on which you wish the preface to begin. You must 
specify the number with an Arabic numeral (the number in the formatted 
result will be a lowercase Roman numeral). If you do not specify a number, 
the default page on which to begin the preface is Roman numeral five. 


The page-number can be either a positive or negative value. 





None. 





This tag must be used in the context of a <FRONT_MATTER> tag. 





<ENDPREFACE> 





DESCRIPTION 


If the preface of a document is placed after the table of contents, you must 
specify the starting page number for the preface. You cannot know what this 
number will be until the document is nearly completed and you know what 
the page count is for the table of contents. 


The table of contents file usually begins on page 3, which is normally output 
as iii, When you have examined the table of contents output, you then can 
know the table of contents’ last page. Specify the next odd number to set the 
correct page number for the preface. 





EXAMPLE 


See the example in the discussion of the <FRONT_MATTER> tag. 


<PREFACE_SECTION> 


<PREFACE_SECTION> 


Creates a major section in the preface of a book to provide information 
such as a summary of changes to the book. 





FORMAT <PREFACE_SECTION> (title) 





ARGUMENTS title 


Specifies the title given to this preface section. 











related tags ¢ = <PREFACE> 
restrictions The <PREFACE_SECTION> tag is valid only within the front matter. 
required None. 

terminator 





DESCRIPTION The <PREFACE-SECTION> tag creates a major section in the preface of a book 
to provide information such as a summary of changes to the book. 





EXAMPLE See the example in the discussion of the <FRONT_MATTER> tag. 
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<PRINT_DATE> 


<PRINT_DATE>. 


Inserts a print date line on the copyright page. 





FORMAT <PRINT_DATE> (date) 





ARGUMENTS date 


Specifies official printing date information for the book. 





related tags None. 





restrictions The <PRINT_DATE> tag is valid only within a copyright page, within 
<FRONT_MATTER> and <ENDFRONT_MATTER> . 





required None. 
terminator 





DESCRIPTION The <PRINT_DATE> inserts a print date line on the copyright page. 





EXAMPLE See the example in the <FRONT_MATTER> tag. 


<PROFILE> 


<PROFILE> 


Indicates that the source file is a profile and that a book build is to be 
performed. 





FORMAT 


<PROFILE> 





ARGUMENTS 


related tags 


None. 





° <ELEMENT > 


. <INCLUDES_FILE> 











restrictions None. 

required <ENDPROFILE> 

terminator 

DESCRIPTION A profile of a book is required in order to build (process) a book. A book’s 
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profile begins with a <PROFILE> tag and ends with the <ENDPROFILE> tag. 
Between the <PROFILE> and <ENDPROFILE> tags, each element of the book 
is introduced with an <ELEMENT> tag. 


Only those files listed with <ELEMENT> tags are included in the book during 
the bookbuild. They should be listed in the profile in the order in which they 
are presented in the book. 


Within a profile file, never include a tag that contains text. Also, do not place 
an <INCLUDE> tag in a profile. 


There are several optional tags that can be included between the <PROFILE> 
and <ENDPROFILE> tags, other than <ELEMENT> tags. These include the 
following: 


° <INDEX_FILE> 


° <CONDITION> and <ENDCONDITION> 


<CONTENTS_FILE> 


<COMMENT> and <ENDCOMMENT> 


<INCLUDES_FILE> 


See Chapter 4 for more information on bookbuilding. 


<PROFILE> 





EXAMPLE 


<PROFILE> <COMMENT> (***Profile for How to Use a Computer***) 


<CONTENTS_FILE> <COMMENT>(***insert table of contents here***) 
<ELEMENT> (Mydisk: [Mydirectory]intro_chap.sdm1) 

<ELEMENT> (Mydisk: [Mydirectory]applications_chap.sdm1) 
<ELEMENT> (Mydisk: [Mydirectory]tools_chap.sdml) 

<ELEMENT> (Mydisk: [Mydirectory] conclusion_chap.sdm1) 

<ELEMENT> (Mydisk: [Mydirectory] questions_app.sdml) 


<INDEX_FILE> <COMMENT>(«**insert index here***) 
<ENDPROF ILE> 


This example illustrates the profile of a book that contains a table of contents, 
four chapters, an appendix and an index. The profile shown in this example 
must be in a file by itself. The file might be called by a name that indicates it 
is a profile, such as “COMPUTER—PROFILE.SDML.” 


Each of the files named in the <ELEMENT> tags should begin with one of the 
book element tags, such as <CHAPTER> (Introduction\introduction_chap). 
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<QUOTE> 


<QUOTE> 


Labels quoted material in the output. 








FORMAT <QUOTE> (quote-text) 
or 
<QUOTE> 
quote-text 
<ENDQUOTE> 
ARGUMENTS quote-text 


related tags 


restrictions 


required 
terminator 


Specifies the quoted text. 





¢ The following tags are used to label single occurrences of a quotation 
mark: 


<DOUBLE_QUOTE> 
<SINGLE_QUOTE> 





None. 





<ENDQUOTE> —Required if the text is not passed as an argument. 





DESCRIPTION 
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The reason for the <QUOTE> tag lies in a mismatch between conventions 
used in the typesetting world and conventions used in the computing world. 
Your terminal keyboard has two possible characters you can use for quotation 
marks: " (ASCII 34) and ‘ (ASCII 39). Neither distinguishes between open 
quotation marks and close quotation marks. You use the same character twice 
to enclose a word in quotation marks: 


"a quoted string” 


Typesetters, on the other hand, scrupulously distinguish between open 
quotation marks and closed quotation marks. The former look like small 
sixes; the latter, like small nines. Look carefully at a typeset document and 
you will immediately see the difference between open and close quotation 
marks. 


<QUOTE> 


In order to obtain the proper quotation marks in your typeset output, you 
must label material inside quotation marks with the <QUOTE> tag. If you 
use the keyboard quote character instead of the <QUOTE> tag, the open and 
close quotes in your typeset document will both look like small, double nines. 
If you use the tag, your output will contain the proper opening and closing 
quotation marks for the font in which your text is set. 





EXAMPLES 


<P>The symbol B will be defined to be the string <QUOTE>(April 


showers) . 


This example may produce the following output: 
The symbol B will be defined to be the string “April showers.” 


Note the placement of the period at the end of the sentence. If you want 
a punctuation mark enclosed outside the quotes, you must not make the 
punctuation mark part of the argument to the <QUOTE> tag. 


<P>Abraham Lincoln once wrote, <QUOTE> I claim not to have controlled 
events, but confess plainly that events have controlled me. <ENDQUOTE> 


This example may produce the following output: 


Abraham Lincoln once wrote, “ I claim not to have controlled events, but 
confess plainly that events have controlled me. ” 
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<REFERENCE> 


<REFERENCE> 


Makes a reference to a symbol-name in a book element or text element. 
When processed, <REFERENCE> is replaced with the current value of the 
symbol-name. 





FORMAT 


<REFERENCE> (symbol-name{ \ keyword]) 





ARGUMENTS 


related tags 
restrictions 


required 
terminator 
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symbol-name 
Specifies the name of a symbol assigned in a book element or text element 
tag (for example, <HEADx> or <TABLE> ). 


Make sure that the symbol-names, that you define in the book element or 
text element tags, do not exceed 31 characters, and only contain alphabetic 
letters, numbers, or underscores in them. Do not begin a symbol-name with 
an underscore. 


keyword 


Specifies an optional keyword indicating the type of text replacement to occur 
in conjunction with the reference: 


Keyword Reference Output 

null Outputs the current value of the symbol and its related 
symbol type text, for example “Figure 3-2.” This is the 
default. 

VALUE Outputs only the current value of the symbol, for example, 


the heading level number or the table number, without any 
related text. 


TEXT Outputs only the text associated with the symbol table 
entry, that is, the caption (for figures, tables, and 
examples), or the heading-text (for chapter, section 
and heading-level tags). 


FULL Outputs all information associated with the symbol, 
including the value, type, and text. 











<REFERENCE> 





DESCRIPTION This tag refers to a symbol-name that is specified as an argument in a text or 
book element. When processed, the <REFERENCE> tag is replaced with the 
current value of the symbol-name that is stored in the cross-reference file. 


A second argument to the tag controls the exact output of the reference. 
When you do not specify a second argument, the output defaults according to 
the symbol type. Table 9-6 summarizes the default output for each type of 


text or book element. 


Table 9-6 Element Types and Default Output of Symbol-Names 


Second Argument to <REFERENCE> 


Text Element (null) VALUE TEXT 


BOOK TITLE The title argument specified in <DEFINE_BOOK_NAME> . 
EXAMPLE Example number number Caption argument 
FIGURE Figure number number Caption argument 
HEADx Heading number number Caption argument 
TABLE Table number number Caption argument 
TEXT STRING The text-string argument specified in <DEFINE_SYMBOL> . 
Book Elements (null) VALUE TEXT 

APPENDIX Appendix letter letter Title argument 
CHAPTER Chapter number number Title argument 
FRONT MATTER None None None 

GLOSSARY None None None 

PART Part number number Title argument 


FULL 


Example number, 
Caption argument 


Figure number, Caption 
argument 


Heading number, 
Caption argument 


Table number, Caption 
argument 


FULL 


Appendix letter, Title 
argument 


Chapter number, Title 
argument 


None 
None 


Part number, Title 
argument 


See Chapter 6 for more information on symbol-names and cross-referencing. 





EXAMPLES 


<REFERENCE>(lognames_tab) shows ten default system logical names. 
<TABLE>(system logical name\lognames_tab) 


This example shows the use of <REFERENCE> and <TABLE> to reference the 
symbol-name of a table. As shown, the symbol-name “lognames_tab” was 
defined in <TABLE> and then referenced with the <REFERENCE> tag. This 


example has the following output: 


Table 1-4 shows ten default system logical names. 


9-193 


<REFERENCE> 


<P>See Chapters <REFERENCE>(lognames_chap\VALUE) and 
<REFERENCE>(filespec_chap\VALUE) to see 


This example shows the use of the tag <REFERENCE> to make a chapter 
number reference without outputting any related information, such as the 
chapter title. This example has the following output: 


See Chapters 3 and 4 to see... 
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<REVISION> 


<REVISION> 


Indicates that the document contains either new or modified information 
and enables the output of the <MARK> tag. 





FORMAT 


<REVISION> /[(UPDATE | \ update-info])] 





ARGUMENTS UPDATE 


related tags 


restrictions 


required 
terminator 


Must be specified if the document is being produced for an update. If 
you specify UPDATE, the file must contain the <UPDATE_RANGE> and 
<ENDUPDATE_RANGE> tags to indicate the pages to be processed. If no 
<UPDATE_RANGE> tags are present, no output will be produced. 


update-info 

Specifies information that is related to the system version and the date of the 
update. If specified, this text appears on the bottom of each page of output in 
the update. 





. <MARK> 


sg <UPDATE_RANGE> 





None. 





None. 





DESCRIPTION The <REVISION> tag can be used in any document type for which you want 


to indicate to reviewers new or changed information. 


This tag enables the <MARK>, <ENDMARK>, <UPDATERANGE> , and 
<ENDUPDATE_RANGE> tags. By default, these tags are defined for all 
document types to be non-operational; thus, if a file is processed without 
the <REVISION> tag, they produce no output. 


When a file that contains the <REVISION> (UPDATE) tag is processed, the table 
of contents and index are handled as follows: 


If the <CONTENTS_FILE> or <INDEX_FILE> tag occurs between the 
bounds of <UPDATE_RANGE> and <ENDUPDATE_RANGE> , and 
/CONTENTS or /INDEX is specified on the command line, the contents 
file or index file is included within the pages for the update range. 


If the <CONTENTS_FILE> or <INDEX_FILE> tag occurs in the file but is 
specified outside the bounds of <UPDATE_RANGE> and <ENDUPDATE_— 
RANGE> tags, and if /CONTENTS or /INDEX is specified on the 
command line, the table of contents file or index file is included in 

the output file. 


<REVISION> 





EXAMPLES 


B 


<DOCTYPE> (SOFTWARE) 
<REVISION> 


<P> 

The following characters are legal in MACRO-11 source programs: 
<LIST> (UNNUMBERED) 

<LE>The letters A through Z. Both upper- and lowercase letters are 
acceptable, although, upon input, lowercase letters are converted to 
uppercase. 

<MARK> 

<LE>Characters in the DEC multinational character set (MCS). A chart 
showing the MCS is located in <REFERENCE>(mcs_app) , 

with a list of directives that support the MCS. 

<LE>The digits 0 through 9. 

<ENDMARK> 

<LE>The characters period <PARENDCHAR>(.) and dollar sign 
<PARENDCHAR>($). These characters are reserved for use as Digital 
Equipment Corporation system program symbols. 

<ENDLIST> 


This example shows the use of the <REVISION> tag in a document that is 
extensively revised. The formatted output may be as follows: 


The following characters are legal in MACRO-11 source programs: 


¢ The letters A through Z. Both upper- and lowercase letters are acceptable, 
although, upon input, lowercase letters are converted to uppercase. 


¢ Characters in the DEC multinational character set (MCS). A chart showing 
the MCS is located in Appendix A, with a list of directives that support 
the MCS. 


¢ = The digits 0 through 9. 


¢ The characters period (.) and dollar sign ($). These characters are 
reserved for use as Digital Equipment Corporation system program 
symbols. 


<REVISION>(UPDATE\July 1986) 


<UPDATE_RANGE> (3\10) 


This example shows the use of the <REVISION> tag in a manual that was 
updated in July of 1986. See the <UPDATE_RANGE> tag for more information 
on identifying a section of updated material. 
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<REVISION_INFO> 


<REVISION_INFO> 


Labels a section on a title page that provides information on what previous 
books have been superseded by the current one. 





FORMAT 


<REVISION_INFO> ([title-text \ Jinformation) 





ARGUMENTS 


related tags 
restrictions 


required 
terminator 


title-text 
Provides heading information. If this argument is not specified, the default 
text “Revision/Update Information” is supplied. 


information 
Provides revision and update information. 





None. 





The <REVISION_INFO> tag is valid only within a title page. 





None. 





DESCRIPTION The <REVISION_INFO> tag labels a section on a title page that provides 


information on what previous books have been superseded by the current 
one. 





EXAMPLE 


See the example in the discussion of the <FRONT_MATTER> tag. 


9-197 


<RIGHT_LINE> 


<RIGHT_LINE> 


Specifies a line of text that is to be right-justified in the current text margin. 





FORMAT <RIGHT_LINE> (text [\ { BIGSKIP | J 





ARGUMENTS _ text 
Specifies a line of text to be set on the right-hand side of the page. 
BIGSKIP 
SMALLSKIP 


Specifies that a set amount of vertical space is to precede the element 
identified as a line or block of text. The actual amount of space inserted 
is determined by the doctype’s design. 





related tags *  <LINE> 
bt <CENTER_LINE> 


restrictions Invalid in monospaced examples and math. 


Right-adjusted text must fit within the current text margin. If you specify text 
that is too wide, the text formatter issues a warning message, and you should 
examine your output. 





EXAMPLE 


<P>Please include the following information: 
<RIGHT_LINE> (Name) 

<RIGHT_LINE> (Address\smallskip) 
<RIGHT_LINE>(Phone Number) 


This example may produce the following output: 
Please include the following information: 


Name 


Address 
Phone Number 
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<RULE> 


<RULE> 


Outputs a rule following headings within a table. 





FORMAT 


<RULE> 





ARGUMENTS 


related tags 


restrictions 


required 
terminator 


None. 





° <TABLE_ROW > 


<TABLE_HEADS > 


<SPAN> 


<TABLE_UNIT_HEADS> 





Can be used only with an argument to the <TABLE_ROW>, <TABLE_HEADS> 
or <TABLE_UNIT_HEADS> tags. 


Must immediately follow the argument text under which the rule is to be 
placed. 








DESCRIPTION 


You can specify that a horizontal rule should be included in a table by placing 
a <RULE> tag inside an argument to one of the following tags: 


: <TABLE_ROW> 
° <TABLE_HEADS> 


e <TABLE_UNIT_HEADS> 


The horizontal length of the rule does not correspond to the dimensions of 
the table. The horizontal length of the rule equals the width of the table 
column (or the spanned columns, if the argument also is preceded by a 
<SPAN> tag). 





EXAMPLE 


See the example in the description of the <TABLE_UNIT> tag. 
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<S> 


<S> 


Labels the system portion of a dialog between user and system in an 
interactive example. 





FORMAT 


<S> (text) 





ARGUMENTS 


related tags 


text 


Specifies the text of the system message. 





bs <INTERACTIVE> 


<U> 














restrictions Invalid in math. 

required None. 

terminator 

DESCRIPTION The <s> tag labels the system portion of a dialog between the system and 

a user. An example containing this type of dialog needs to have both parts 

identified 1 in order to differentiate the two types of text in the source code, the 
output, or both. 
The <S> and <U> tags are used also to differentiate the system and user 
text inside of examples created with the <EXAMPLE_SEQUENCE> and <EXI> 
tags, in the Software Doctype. For more information on this doctype, refer to 
the VAX DOCUMENT User Manual, Volume 2. 

EXAMPLES 

| <P>The system prompt <S>($) indicates you can enter a command. 
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This example may produce the following output: 


The system prompt $ indicates you can enter a command. 


<S> 


<P>The following example of VAXMAIL contains messages from both 
the system and a user of the system: , 

<INTERACTIVE> 

<U> (mail) 

<S>(MAIL> )<U>(send) 

<S>(To: )<U>(nodename: : Courtney) 

<S>(%MAIL-E-NOSUCHUSR, no such user COURTNEY at node NODENAME) 
<ENDINTERACTIVE> 


Note that one space is included after a prompt in an <S> tag argument. 
This example may produce the following output: 


The following example of VAXMAIL contains messages from both the system 
and a user of the system: 


mail 

MAIL> send 

To: nodename: : Courtney 

YMAIL-E-NOSUCHUSR, no such user COURTNEY at node NODENAME 


For another example, see the example in the discussion of the 
<INTERACTIVE> tag. 
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<SAMPLE_TEXT> 


<SAMPLE_TEXT> 


Distinguishes, typographically, an extract of text. 





FORMAT <SAMPLE_TEXT> 





ARGUMENTS _ None. 











related tags ¢ = <CENTER_LINE> 

restrictions Within the sample text, if you want to show a paragraph, you must label 
it with a <P> tag. The <SAMPLE_TEXT> tag does not provide paragraph 
spacing. 

required <ENDSAMPLE_TEXT> 

terminator 





DESCRIPTION The <SAMPLE_TEXT> tag labels text that requires distinctive formatting. The 
text so labeled will be filled and justified and indented from the normal text 
margins. 





EXAMPLE 


<P>An evolutionary trend toward niche divergence typically results. 
<SAMPLE_TEXT> 

<P>Taken from Brown,T.J.: The Skull of the Pronghorn. The McMullen Company, 
1970. 

<ENDSAMPLE_TEXT> 


This example may produce the following output: 
An evolutionary trend toward niche divergence typically results. 


Taken from Brown,T.J.: The Skull of the Pronghorn. The 
McMullen Company, 1970. 
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<SET_APPENDIX_LETTER> 


<SET_APPENDIX_LETTER> 


Overrides the default appendix letter assigned to an appendix by VAX 
DOCUMENT. 





FORMAT 


<SET_APPENDIX_LETTER> (appendix-letter) 





ARGUMENTS 


related tags 


restrictions 


required 
terminator 


appendix-letter 
Specifies the letter of the appendix. This argument must be a letter from A to 
Z. 





bs <APPENDIX> 
bg <SET_CHAPTER_NUMBER> 


e The MILSPEC doctype <SET_APPENDIX_NUMBER> tag. 





This tag should not be used in a file that will be included in a bookbuild 
or element build. Processing this tag in a bookbuild generates a warning 
message. 





None. 





DESCRIPTION 


Use the <SET_APPENDIX_LETTER> tag to override the default appendix letter 
created by VAX DOCUMENT. The <SET_APPENDIX_LETTER> tag resets 

the current appendix letter; if you specified C as the argument, the next 
<APPENDIX> tag would be Appendix C. 


You should place the <SET_APPENDIX_LETTER> tag in your SDML 

file before the <APPENDIX> tags you want it to affect, because the 
<SET_APPENDIX_LETTER> tag affects only the <APPENDIX> tags that follow 
it. The new appendix letter you specify resets the numbering for all following 
appendixes. For example, if you use the <SET_APPENDIX_LETTER> tag to 

set the appendix letter to “C,” the next appendix will be Appendix C, the 
appendix following that appendix will be Appendix D, and so on. 


<SET_APPENDIX_LETTER> can be used multiple times in an SDML file. 


<SET_APPENDIX_LETTER> 





EXAMPLE In the following example the appendix “Error Messages” is explicitly set to 
C using the <SET_APPENDIX_LETTER> tag. This will cause any subsequent 
appendixes to be numbered beginning with the letter D unless another 
<SET_APPENDIX_LETTER> tag is used to reset the current appendix letter. 


<SET_APPENDIX_letter>(C) 
<APPENDIX>(Error Messages\error_msg_ap) 
<p> 

The following error messages... 
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<SET_CHAPTER_NUMBER> 


<SET_CHAPTER_NUMBER> 


Overrides the default chapter number assigned to a chapter by VAX 
DOCUMENT. 





FORMAT 


<SET_CHAPTER—_NUMBER > (chapter-number) 





ARGUMENTS 


related tags 


restrictions 


required 
terminator 


chapter-number 
Specifies the number of the chapter. This argument must be a positive 
integer. 





s <CHAPTER> 


be <SET_APPENDIX_LETTER> 





This tag should not be used in a file that will be included in a bookbuild 
or element build. Processing this tag in a bookbuild generates a warning 
message. 





None. 





DESCRIPTION Use the <SET_CHAPTER_NUMBER> tag to override the default chapter number 


created by VAX DOCUMENT. The <SET_CHAPTER_NUMBER> tag resets the 
current chapter number; if you specify 13 as the chapter number, the next 
<CHAPTER> tag becomes Chapter 13. This numbering also affects all other 
<CHAPTER> tags in your SDML file so that the subsequent chapter becomes 
Chapter 14, and so on. 


The <SET_CHAPTER_NUMBER> tag should be placed in your SDML file before 
the <CHAPTER> tags that you want to affect, because the <SET_CHAPTER_— 
NUMBER> tag affects only the <CHAPTER> tags that follow it. 


The new chapter number you specify resets the numbering for all following 
chapters. For example, if you use the <SET.CHAPTER_NUMBER> tag to set the 
chapter number to 13, the next chapter will be Chapter 13, and the chapter 
following that chapter will be Chapter 14, and so on. 


The <SET_CHAPTER_NUMBER> can be used multiple times in an SDML file. 
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<SET_CHAPTER_NUMBER> 





EXAMPLE In the following example the chapter is set to 13 using the 
<SET_CHAPTER_NUMBER> tag. This will cause any subsequent chapters 
to be numbered beginning with number 14 unless another <SET_CHAPTER— 
NUMBER> tag is used to reset the current chapter number. 


<SET_CHAPTER_NUMBER> (13) 

<CHAPTER> (Supported Devices\sup_dev_chap) 
<p> 

The primary supported devices... 
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<SET_CONDITION> 


<SET_CONDITION> 


Creates or removes a condition name. 





FORMAT 


<SET_CONDITION> (condition-name[ \ REMOVE]) 





ARGUMENTS 


related tags 


restrictions 


required 
terminator 


condition-name 
Specifies a name used to conditionalize a portion of your SDML file. This 
name is limited to 28 characters in length. 


REMOVE 


Causes the condition-name to be removed. 





bs <CONDITION> 





None. 





None. 





DESCRIPTION The <SET_CONDITION> tag is used to create or remove a condition name. 


Conditions are specified with the <CONDITION> tag. 
For a complete explanation of creating conditional text, refer to Chapter 4. 


Normally, a condition name is created at the front of your input and remains 
in effect for the whole of the input file. In the rare occasion when you want to 
process a portion of the input without the condition name, it can be removed 
by repeating the <SET_CONDITION> tag with the REMOVE argument. 


You can use the /CONDITION qualifier on the DOCUMENT command line 
instead of placing the <SET_CONDITION> tag into your file. For example, 
you might use the command line qualifier “/CONDITION=local” instead of 
putting “ <SET_CONDITION> (local)” in your input file. 





EXAMPLE 


See the example under the discussion of the <CONDITION> tag. 
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<SET_FIGURE_FILE_SPACING_DEFAULT> 


<SET_FIGURE_FILE_SPACING_DEFAULT> 


Overrides the default for vertical blank space that appears before and after 
the inclusion of a graphics file. 





FORMAT 


<SET_FIGURE_FILE_SPACING_DEFAULT> ([space-before] 
\ [space-after]) 





ARGUMENTS 


related tags 


space-before 

Specifies the amount of vertical space in picas that is to be output before 
the graphic file (there are 6 picas to an inch). This argument may be a 
nonnegative integer or decimal number, including zero. 


space-after 

Specifies the amount of vertical space in picas that is to be output following 
the graphic file (there are 6 picas to an inch). This argument may be a 
nonnegative integer or decimal number, including zero. 





° <FIGURE_FILE> 











restrictions None. 

required None 

terminator 

DESCRIPTION Each document design specifies default values for spacing that is inserted 
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before and after a graphics file included using the <FIGURE_FILE> tag. These 
defaults assume that the actual graphic file itself does not have any built-in 
white space. 


In some instances, graphics files may have included white space, and you 
may not be able to remove it from the graphics file itself. In these instances, 
you can use the <SET_FIGURE_FILE_SPACING_DEFAULT> tag to modify the 
amount of white space that VAX DOCUMENT places before and after the 
graphics file. 


The values specified by the <SET_FIGURE_FILE_SPACING_DEFAULT> tag 
remain in effect for all subsequent figures, or until you use the <SET_FIGURE_ 
FILE_SPACING_DEFAULT> tag again. 


If you do not specify one of the arguments to the <SET_FIGURE_FILE_ 
SPACING_DEFAULT> tag, then that spacing remains the same as though 
the tag had not been used. 


<SET_FIGURE_FILE_SPACING_DEFAULT> 





EXAMPLES 


<SET_FIGURE_FILE_SPACING_DEFAULT>(0\1.24) 
<FIGURE>(Graphic File Inclusion) 
<FIGURE_FILE>(LNO3\MY_FILES: SANTA.SIX\13.76) 
<ENDF IGURE> 


In this example, the figure file spacing is set to 0 picas before a figure and 
1.24 picas after a figure. All subsequent graphics files included using the 
<FIGURE_FILE> tag will also have this amount of white space around the 
graphic figure. 


<SET_FIGURE_FILE_SPACING_DEFAULT>(10\0) 
<FIGURE>(Graphic File Inclusion) 
<FIGURE_FILE>(LNO3\MY_FILES: SANTA. SIX\13. 76) 
<ENDF IGURE> 
<SET_FIGURE_FILE_SPACING_DEFAULT> (2\2) 


In this example, the figure file spacing is set to 10 picas before the figure and 
0 picas after it. The use of the second <SET_FIGURE_FILE_SPACING_DEFAULT> 
tag resets the amount of spacing for any subsequent figures to 2.0 picas before 
the graphic figure and 2.0 picas after the graphic figure. 
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<SET_TABLE_ROW_BREAK_DEFAULT> 


<SET_TABLE_ROW_BREAK_—DEFAULT > 


Overrides the default value for a multipage table’s first valid break. 





FORMAT 


<SET_TABLE_ROW_BREAK_DEFAULT> (number-of-rows) 





ARGUMENTS 


related tags 


restrictions 


required 
terminator 


number-of-rows 
Specifies the number of rows that the table tags will use as a default when it 
creates multipage tables. number-of-rows must be a positive integer. 


You can specify <SET_TABLE_ROW_BREAK_DEFAULT> anywhere in an SDML 
file. The value you specify using this tag will affect subsequent tables until 
the next occurrence of the tag or until the end of the file. 





° <TABLE_ROW_BREAK> 





None. 





None. 


DESCRIPTION 
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By default, tables are considered “multipage,” that is, if there is not enough 
room on the current page for a table, it will be continued onto subsequent 
pages, with any captions and headings repeated at the top of each new page. 
When the text formatter chooses places in the table at which to insert page 
breaks, it normally breaks the table between <TABLE_ROW> tags. By default, 
it assumes that it is all right to break a table between any two table rows after 
the first. 


You can override this default behavior in the following ways: 


Specify the <SET_TABLE_ROW_BREAK_DEFAULT> tag to provide a default 
number of rows that must be on the first page of the table. For example, 
if you specify <SET_TABLE_ROW_BREAK_DEFAULT> (3), any subsequent 
table will not be broken until after the third row. (You might want to use 
this default if your table consists of single-line items, for instance.) 


Specify the table attribute CONTROLLED, which indicates that you are 
going to specify, explicitly, the range in which the table will be allowed 
to break. You then must use <TABLE_ROW_BREAK> (FIRST) and <TABLE_ 
ROW_BREAK> (LAST) to indicate the first and last allowable page break 
points. Between these two tags, the table may be broken between any 
two <TABLE_ROW> tags. 


Use the KEEP attribute to indicate that the table must not be broken 
across pages, unless it is longer than a page. 


Use <VALID_TABLE_ROW_BREAK> to indicate a place within a long table 
row that is an allowable break point. 


<SET_TABLE_ROW_BREAK_DEFAULT> 


e Use <NESTED_TABLE_BREAK> to indicate a place in a nested table that is 
an allowable break point (a nested table is a table that is nested within an 
argument to another table’s <TABLE_ROW> ). 





EXAMPLE 


<SET_TABLE_ROW_BREAK_DEFAULT> (5) 
<TABLE> 

<TABLE_ATTRIBUTES> (SINGLE_SPACED) 
<TABLE_SETUP> (2\5) 
<TABLE_HEADS>(Code\Numeric Value) 
<TABLE_ROW> (A\1) 

<TABLE_ROW>(B\2) 


<TABLE_ROW> (Z\26) 
<ENDTABLE> 
In this example, a table consists of short, one-line items. The <SET_TABLE— 


ROW_BREAK_DEFAULT> tag is used to indicate that this table, and any 
following it, must not be broken until after the fifth row. 


9-211 


<SINGLE_QUOTE> 


<SINGLE_QUOTE> 


Outputs, within text, a single quotation mark as it appears on a keyboard. 





FORMAT 


<SINGLE_QUOTE> 





ARGUMENTS 


related tags 


restrictions 


required 
terminator 


None. 





e <DOUBLE—QUOTE> 


° <QUOTE> 





None. 





None. 


DESCRIPTION 
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The reason for the <SINGLE_QUOTE> tag lies in a mismatch between 
conventions used in the typesetting world and conventions used in the 
computing world. Your terminal keyboard has two possible characters 
you can use for quotation marks: ” (ASCII 34) and ’ (ASCII 39). Neither 
distinguishes between open quotation marks and closed quotation marks. 
You use the same character twice to enclose a word in quotation marks: 


"a quoted string" 
or 
‘a quoted string’ 


Typesetters, on the other hand, scrupulously distinguish between open 
quotation marks and closed quotation marks. The former look like small 
sixes; the latter, like small nines. (Actually, in the text font used on the LNO1, 
the open quotation marks look like splinters with their points up; the closed 
quotation mark looks like splinters with their points down.) Look carefully at 
any typeset document and you will immediately see the difference between 
open and closed quotation marks. 


To obtain a single quotation mark in your output, looking as it does when 
shown on the terminal (as an apostrophe), use the <SINGLE_QUOTE> tag. If 
you simply use the keyboard single quotation mark instead of the tag, your 
output will contain unmatched closed single quotation marks—one half of 
what should be a matched pair. (See the example section.) If you use the 
tag, your output will contain a single quotation mark that looks like the one 
produced by the terminal keyboard. 


<SINGLE_QUOTE> 





EXAMPLE 


<P>You can cause the translation of a symbol by using a single 


quotation mark <PARENDCHAR>(<SINGLE_QUOTE>) directly in front of it. 


This example shows the use of the <SINGLE_QUOTE> tag. It may produce 
the following output: 


You can cause the translation of a symbol by using a single quotation mark 
(‘) directly in front of it. 


<P>You can cause the translation of a symbol by using a single 


quotation mark (') directly in front of it. 


This example shows what your output would be like without using the tag, 
but just entering the character from the keyboard. 


You can cause the translation of a symbol by using a single quotation mark 
(’) directly in front of it. 
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<SPAN> 


<SPAN> 


Specifies that the accompanying argument in a table row or a table head 
should span more than one table column. 





FORMAT 


<SPAN> (number-of-columns| \ LEFT)) 





ARGUMENTS 


related tags 


restrictions 


required 
terminator 


number-of-columns 

Specifies the number of table columns to be spanned by the text immediately 
following the <SPAN> tag. This argument must be a whole number and 
must be no larger than the number of table columns remaining in the table 
row, including the table column in which the <SPAN> tag itself was placed. 


LEFT 


Specifies that the text of the argument should be aligned to the left in the 
left-most of the spanned columns. If this argument is omitted the text of the 
argument is centered in the spanned columns. 





s <RULE> 
° <TABLE_HEADS> 


® <TABLE_UNIT_HEADS > 





Can be used only within an argument to the <TABLE_ROW>, <TABLE_ 
HEADS> , or <TABLE_UNIT_HEADS> tags. 


Must immediately precede the argument text. 





None. 


DESCRIPTION 


The <SPAN> tag specifies that the argument text that follows the tag should 
not be confined to a single table column, but should span additional columns. 
The text is displayed without regard for the gutter that separates the columns. 
The text is centered in the spanned columns, unless the LEFT argumertt is 
supplied. 


If the text length exceeds the width of the spanned columns it is broken at a 
word boundary and displayed on additional table lines. Any additional lines 
of text are centered or left justified to agree with the alignment of text in the 
first line. 


Use the <RULE> tag to place a rule beneath a spanned heading created using 
the <SPAN> tag. 


<SPAN> 





EXAMPLES 


<TABLE> 

<TABLE_SETUP> (3\12\12) 
<TABLE_HEADS>(<SPAN>(3)Types of Ancient Weaponry) 
<TABLE_UNIT> 

<TABLE_UNIT_HEADS> (Polearms) 

<TABLE_ROW> (Spear\Javelin\Halberd) 
<ENDTABLE_UNIT> 

<TABLE_UNIT> 
<TABLE_UNIT_HEADS> (Maces\<SPAN> (2\LEFT) Swords<RULE>) 
<TABLE_UNIT_HEADS>( \Short swords\Long swords) 
<TABLE_ROW>(Great Mace\Gladius\Great Sword) 
<ENDTABLE_UNIT> 





<ENDTABLE> 
This example shows how the <SPAN> tag is used to center the table heading 
over three columns and also how the LEFT keyword is used to position a 
table unit heading; note the use of the global <RULE> tag in this example. 
This example may have the following output: 
Types of Ancient Weaponry 
Polearms 
Spear Javelin Halberd 
Maces Swords 
Short swords Long swords 
Great Mace Gladius Great Sword 
<TABLE> 


<TABLE_SETUP>(5\9\9\9\9) 
<TABLE_ROW>(\<SPAN>(2)Small Fixture\<SPAN>(2)Large Fixture) 


<TABLE_ROW> (Component \Minimum\Maximum\Minimum\Maximum) 
<ENDTABLE> 


The output of this example is expected to look approximately like this: 


Small Fixture Large Fixture 
Component Minimum Maximum Minimum Maximum 


However, the <SPAN> tag will actually center “Small Fixture” correctly, but 
“Large Fixture” may be pushed too far to the right: 


Small Fixture Large Fixture 
Component Minimum Maximum Minimum Maximum 
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<SPAN> 


This occurs because the <SPAN> tag attempts to span the last column to 
the margin. To fix this problem, code the table to specify an additional 
column and specify a width for the next to last column, thereby limiting the 
distance that is spanned. The following example gives an example of such a 
correction: 


<table> 

<table_setup>(6\8\8\8\8\8) 

<table_row>(\<span>(2)Small Fixture\<span>(2)Large Fixture) 
<table_row> (Component \Minimum\Maximum\Minimum\Maximum) 
<endtable> 


Produces: 


Small Fixture Large Fixture 
Component Minimum Maximum Minimum Maximum 
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<SPECIAL_CHAR> 


<SPECIAL_CHAR> 


Provides access to special characters that are not available on the terminal 
keyboard. 





FORMAT 


<SPECIAL_CHAR> (keyword) 





ARGUMENTS 


related tags 


restrictions 


required 
terminator 


keyword 
Specifies a keyword associated with the special character you want to produce 
in your output file. The following are valid keywords: 


Keyword Character 
FULL__DIAMOND + 
TRADEMARK_SYMBOL ad 
REGISTERED_SYMBOL ® 
SECTION_SIGN § 

DAGGER t 
DOUBLE_DAGGER t 
OPEN_DOUBLE_BRACKET [ 
CLOSE_DOUBLE_BRACKET I 





: <MCS> 


e <MATH_CHAR> 





The character must be a non-math character. 





None. 


DESCRIPTION The <SPECIAL_CHAR> tag provides access to special characters that are not 


available on the terminal keyboard. 
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<SPECIAL_CHAR> 





EXAMPLE 


%COPY-I-COPIED, $DISK1i: [MYDIRECTORY] MYFILE.PLI ;5<SPECIAL_CHAR>(FULL_DIAMOND) 
copied to $DISK1: [YOURDIRECTORY] YOURFILE.PLI;5 


In this example, the special character ¢ is used in an example of terminal 


output to show that text wraps at the end of a line. The example may 
produce the following output: 


%COPY-I-COPIED, $DISK1: [MYDIRECTORY] MYFILE.PLI;5 
+ 


copied to $DISK1: [YOURDIRECTORY] YOURFILE.PLI;5 
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<SUBHEADx> 


<SUBHEADx> 


Marks an unnumbered subsidiary heading. 





FORMAT <SUBHEAD1 > (heading-text) 
<SUBHEAD2> (heading-text) 





ARGUMENTS _heading-text 
The text of the subsidiary heading. 





related tags e  <HEAD1> through <HEAD6> 


° <CHEAD> 








restrictions None. 
required None. 
terminator 





DESCRIPTION The <SUBHEADI> and <SUBHEAD2> tags label unnumbered subsidiary 
headings. Each reflects a logical hierarchy within the structure of the text. 


These subheadings are not numbered and do not appear in the table of 
contents. They cannot be readily used for cross-references and should be 
used only when the clarity of your exposition requires such a fine level of 
distinction. 


In some book doctypes, the distinction is made between <SUBHEAD1> and 
<SUBHEAD2> by making <SUBHEAD2> a run-in heading. The doctype 
design controls the text formatter’s placement of the text following the 
<SUBHEAD2> . Whether or not you expect the heading to be run-in, always 
tag the text element following the heading (for example, always mark a 
paragraph with a <P> tag). 





EXAMPLE 


<SUBHEAD1>(Using a Subhead) 

<P>The use of subheads should be restricted to occasions when the clarity 

of your exposition absolutely requires one. 
This example might produce output like the following: 
Using a Subhead 


The use of subheads should be restricted to occasions when the clarity of 
your exposition absolutely requires one. 
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<TABLE> 


<TABLE> 


Begins a sequence of columnar data. 





FORMAT 


<TABLE> [(table-caption[ \ symbol-name])] 





ARGUMENTS 


related tags 


restrictions 


required 
terminator 
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table-caption 

Specifies the text of the caption to be associated with the table. The table 
caption and the associated table number will be written to the table of 
contents for the document. 


Note that the presence of this argument indicates that the table is a formal, 
numbered table. If the body of the table spans more than a single page of 
text, the table caption is repeated on each page on which the table continues. 


symbol-name 

Specifies the symbolic identifier to be associated with the table. The symbol 
identifier will be assigned a numeric value which will be the current table 
number. The symbol and its value are placed in the symbol table. 


The symbol name can consist of up to 64 alphanumeric characters or 
underscores. It must not begin with a leading underscore. 





® <TABLE_ATTRIBUTES > 
° <TABLE_SETUP> 

° <TABLE_HEADS> 

bd <TABLE_ROW> 

® <TABLE_FILE> 

° <TABLE_UNIT> 

° <TABLE_KEY> 

° <TABLE_SPACE> 

° <SPAN> 


° <RULE> 


The <TABLE> tag is not valid in monospaced examples, in math, or in 
figures. 


<ENDTABLE> 


<TABLE> 





EXAMPLE 


<P>An expression can evaluate to either an integer or 

a string value, depending on the types of values used in the expression 
and the operations used to manipulate them. 
<REFERENCE>(express_modes_tab) summarizes the rules 

for determining the mode of an expression. 

<TABLE>(Rules for Determining Expression Modes\express_modes_tab) 
<TABLE_ATTRIBUTES> (MULTIPAGE) 

<TABLE_SETUP> (2\33) 

<TABLE_HEADS>(Expression\Value Type) 

<TABLE_ROW>(Integer value\Integer) 

<TABLE_ROW> (String value\String) 

<TABLE_ROW>(Integer lexical function\Integer) 

<TABLE_ROW_BREAK> (first) 

<TABLE_ROW>(String lexical function\String) 

<TABLE_ROW>(Integer symbol\Integer) 

<TABLE_ROW>(String symbo1l\String) 


<ENDTABLE> 


This example shows how to produce a two-column table. This example may 
produce the following output: 


An expression can evaluate to either an integer or a string value, depending 
on the types of values used in the expression and the operations used to 
manipulate them. Table x—x summarizes the rules for determining the mode 
of an expression. 


Table x—-x Rules for Determining Expression Modes 








Expression Value Type 
Integer value Integer 
String value String 
Integer lexical function Integer 
String lexical function String 
Integer symbol Integer 
String symbol String 
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<TABLE_ATTRIBUTES > 


<TABLE_ATTRIBUTES > 


Specifies special formatting for a table. 





FORMAT 


<TABLE_ATTRIBUTES> (keyword-1 
[ \ keyword-2... \ keyword-5]) 





ARGUMENTS keyword-1...keyword-5 


Keyword 
CONTROLLED 


KEEP 


MAXIMUM 


MULTIPAGE 


SINGLE_SPACED 


WIDE 
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Specifies one to five keywords that indicate special formatting for the table. 
These keywords are listed in the following table. Note that the MULTIPAGE 
and KEEP keywords are mutually exclusive and cannot be used together. 


Description 


Indicates, for a multipage table, that the table page breaking will be under explicit 
control of <TABLE_ROW_BREAK> tags. When you use the CONTROLLED keyword, 
you must specify <TABLE_ROW_BREAK> (FIRST) and <TABLE _ROW-_BREAK> (LAST) 
tags to give the text formatter an allowance for page breaking. 


This keyword may not be used with the KEEP keyword. 


Indicates that the table must be kept on one page. If there is not enough room on the 
current page, a new page is output. If the table exceeds the length of a page, the text 
formatter issues a warning message and not all the table will be output. 


Indicates that the text of the table will be adjusted to a smaller point size in order to fit 
within the left and right margins of the page. Note that if this argument is not specified, 
and if a table is determined during text formatting to be too wide, the text formatter 
will adjust the size of the text automatically. 


Indicates that the table is either of the following: 
e Longer than a page 


e Allowed to break across pages 


This is the default. If MULTIPAGE is specified, the <TABLE_ROW_BREAK> tag can be 
used to control page breaks. 


Specifies that the rows in the table are to be single-spaced; that is, there should be no 
more vertical space between lines of different table rows than there are between lines 
within the same table row. 


Specifies that the width of the table exceeds the document's default width for text. 
Depending on the document type, this argument may be interpreted as follows: 


e If the document style contains a left margin area that is normally used for headings, 
the table’s width will span that area as well as the normal text area. 


e If the document uses a multicolumn format, the table suspends multicolumn output 
while the table is processed. The table is output, and then multicolumn output is 
restored. 


<TABLE_ATTRIBUTES > 





related tags ©  <TABLE> 
S <TABLE_SETUP> 











restrictions 
¢ Must be in the context of a table. 
e Must precede the <TABLE_SETUP> tag. 
¢ WIDE and MAXIMUM might not produce error-free output for 
monospaced output devices. 
required None. 
terminator 
EXAMPLE 


<TABLE>(Equivalence Names for Default Process Logical Names\equiv_names_proc_tab) 
<TABLE_ATTRIBUTES> (WIDE\KEEP) 

<TABLE_SETUP> (4\8\10\12) 

<TABLE_HEADS> (Logical Name\Interactive\Batch\Command Procedure) 
<TABLE_ROW> (SYS$COMMAND\Terminal\Disk\Terminal) 

<TABLE_ROW> (SYS$DISK\Disk\Disk\Disk) 

<TABLE_ROW> (SYS$INPUT\Terminal\Disk\Disk) 

<TABLE_ROW> (SYS$ERROR\Terminal\Log file\Terminal) 

<TABLE_ROW> (SYS$LOGIN\Directory\Directory\Directory) 
<TABLE_ROW> (SYS$NET\\\) 

<TABLE_ROW> (SYS$OUTPUT\Terminal\Log file\Terminal) 

<TABLE_ROW> (SYS$SCRATCH\Directory\Directory\Directory) 
<TABLE_ROW>(TT\Terminal\Null device\Terminal) 

<ENDTABLE> 


This example may produce the following output: 


Table x—-x Equivalence Names for Default Process Logical Names 


Logical Name Interactive Batch Command Procedure 
SYS$COMMAND Terminal Disk Terminal 

SYS$DISK Disk Disk Disk 

SYS$INPUT Terminal Disk Disk 

SYS$ERROR Terminal Log file Terminal 

SYS$LOGIN Directory Directory Directory 

SYSSNET 

SYSSOUTPUT Terminal Log file Terminal 
SYS$SCRATCH Directory Directory Directory 

TT Terminal Null device Terminal 
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<TABLE_FILE> 


<TABLE_FILE> 


Causes a separate file containing a formal table to be included in the SDML 
input file. 





FORMAT 


<TABLE_FILE> (file-spec) 





ARGUMENTS 


related tags 


restrictions 


required 
terminator 


file-spec 

The file specification of the file to be included. If a logical name is specified 
instead, and the SDML input file is an element of a book, you can define 
the logical name using an <INCLUDES_FILE> tag in the book’s profile. If the 
source file is not an element of a book, or if the profile does not contain the 
<INCLUDES_FILE> tag, be sure to define the logical name before processing 
the file through VAX DOCUMENT. 





e <TABLE> 





Can be used only in the context of a <TABLE> tag. 


The <TABLE_FILE> tag must be placed after the <TABLE> tag. 





None. 


DESCRIPTION 


The <TABLE_FILE> tag causes the entire contents of a specified file to be 
included at this point in the SDML file. (It is identical in action to the 
<INCLUDE> tag.) The included file should be an SDML file containing a 
completely coded table. 


By keeping a table in a separate SDML file, you can include the table in more 
than one document, or in chapters of the same document, without having 

to reproduce the code. In each location, the table can be given a different 
number. 





EXAMPLES 


<TABLE>(Default VMS File Types\Stand_Filetypes_Tab) 


<TABLE_ATTRIBUTES> (wide) 
<TABLE_FILE> (Standard_Filetypes) 


<ENDTABLE> 


This example shows a wide table that is contained in a separate file. The 
logical name of the file (Standard_Filetypes) should be recorded in the profile 
along with the proper file specification for the file. See the next example for a 
sample profile entry. 


<TABLE_FILE> 


It should be noted that this included table file will not process individually. 
It will only process when included in another SDML file that specifies the 
<TABLE> and <ENDTABLE> tags. 


2 <REFERENCE>(command_sum_tab) lists all the commands. 
<TABLE_FILE>(endlist.sdml) 


In this example, the file ENDLIST.SDML may contain all the tags required for 
the table: 


<TABLE>(Command Summary\command_sum_tab) 
<TABLE_ATTRIBUTES> (Multipage) 
<TABLE_SETUP> (2\18) 


This example assumes that the table is being used in only one document. 
Placing the table in a separate file allows you to process it individually, or in 
the context of the file in which it occurs. 
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<TABLE_HEADS> 


<TABLE_HEADS > 


Specifies column headings for each column in the table. 





FORMAT 


<TABLE_HEADS > (col-heading/ \ col-heading...]) 





ARGUMENTS 


related tags 


col-heading 

Specifies the heading for each column; the first argument is the heading for 
the first column. Up to nine arguments can be specified, depending on the 
number of columns in the table. 





° <TABLE_UNIT> 


<TABLE_HEADS > 


<SPAN> 


<RULE> 














restrictions 
e Only used in the context of a <TABLE> tag. 
e Maximum of nine column headings. 

required None. 

terminator 

DESCRIPTION This tag is not required in a table tags sequence. However, it allows you to 
specify a heading for each column of a table if headings are needed. 
A heading can be any length, and is automatically formatted correctly on one 
or more lines (see the long heading in the example in <TABLE_ROW?> ). 
Within tables, the <TABLE_HEADS> tag can be used to specify multipage 
headings for a table. It can also be used to place new headings in the middle 
of a table. However, they can not be used in a table unit. 

EXAMPLE See the example for the <TABLE_ROW> tag. 


<TABLE_KEY> 


<TABLE—KEY > 


Begins a key or legend for a table. 





FORMAT 


<TABLE_KEY > 





ARGUMENTS 


related tags 


restrictions 


required 
terminator 


None. 





° <TABLE_KEYREF> 


bd <FOOTNOTE> 





Can be used only within the context of a table. 


Must appear immediately after the tag <TABLE_SETUP> , either before or after 
any <FOOTNOTE> tags. 


When a <TABLE_KEY> is used, the number of possible footnotes for the same 
table is reduced from 12 to 11. 


The tags that can be used between <TABLE_KEY> and <ENDTABLE_KEY> are 
restricted to the <P>, <LIST> and emphasis tags. For example, you cannot 
use a <TABLE_ROW> tag within the table key. 


The <TABLE_KEY> tag is not valid in a nested table. <TABLE_KEY> must 
follow the <TABLE_SETUP> tag for the outermost table. 





<ENDTABLE_KEY> 





DESCRIPTION Abbreviations or special terms are often used in a table, either in the column 


headings, or in the entries of the table. The table may then need a key or 
legend printed below it that explains the special terms. The <TABLE_KEY> 
tag begins such a table key. 


A table key differs from a table footnote as the table key is not numbered and 
does not refer to a callout in the table. Only one table key can be declared 
for a table, whereas up to 12 footnotes are possible. 


The table key is declared immediately after the <TABLE_SETUP> tag that 
begins the table and before the first tag that begins the table rows. This 
placement is identical to the placement for footnotes in a table. If footnotes 
are present also, they either can precede or follow the table key declaration. 


The table key is printed at the foot of the table, following any footnotes. It is 
printed only if the <TABLE_KEYREF> tag appears in the table. Place <TABLE_ 
KEYREF> anywhere in the argument list that supplies the column heads. This 
placement guarantees that the table key is printed at the foot of the table and 
on each page of a multipage table. (If you want the table key to appear only 
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<TABLE_KEY> 


on selected pages of a multipage table, place <TABLE_KEYREF> with the table 
row tags for the selected pages.) 





EXAMPLE 


<table>(Compatability of Lock Modes\lock_tab) 
<table_attributes>(wide\keep) 
<table_setup>(7\10\5\5\5\5\5) 


<table_key> 
<emphasis>(Key to Lock Modes\bold) 
<list> (simple) 
<le>NL---Null lock 
<le>CR---Concurrent read 
<le>CW---Concurrent write 
<le>PR---Protected read 
<le>PW---Protected write 
<le>EX---Exclusive lock 
<ENDLIST> 
<endtable_key> 


<table_heads>(Mode of Requested\ 
<span>(5)Mode of Currently Granted Locks<rule>) 

<table_heads>(Lock<table_keyref>\NL\CR\CW\PR\PW\EX) 
<table_row> (NL\Yes\Yes\Yes\Yes\Yes\Yes) 
<table_row>(CR\Yes\Yes\Yes\Yes\Yes\No) 
<table_row>(CW\Yes\Yes\Yes\No\No\No) 
<table_row>(PR\Yes\Yes\No\Yes\No\No) 
<table_row>(PW\Yes\Yes\No\No\No\No) 
<table_row>(EX\Yes\No\No\No\No\No) 


<endtable> 


This example produces the following output: 


Table x—x Compatibility of Lock Modes 








ee - Mode of Currently Granted Locks 

Lock NL CR CW PR PW EX 

NL Yes Yes Yes Yes Yes Yes 
CR Yes Yes Yes Yes Yes No 

CW Yes Yes Yes No No No 

PR Yes Yes No Yes No © No 

PW Yes Yes No No No No 

EX Yes No No No No No 





Key to Lock Modes 


NL—Null lock 
CR—Concurrent read 
CW—Concurrent write 
PR—Protected read 
PW—Protected write 
EX—Exclusive lock 
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<TABLE_KEYREF> 


<TABLE_KEYREF> 


Specifies that a table key be printed below the table (or portion of the 
table) in which this tag appears. 





FORMAT 


<TABLE_KEYREF> 





ARGUMENTS 


related tags 


restrictions 


required 
terminator 


None. 





as <TABLE_KEY> 





Can be used only within the context of a table in which <TABLE_KEY> is 
specified. 


Invalid in nested tables. 


Can only be used at the end of an argument list and cannot be embedded in 
text; the end of an argument list is indicated by a backslash (\) or a closing 
parenthesis ()). 





None. 





DESCRIPTION 


The <TABLE_KEYREF> tag specifies that the table key (defined with the 
<TABLE_KEY> ... <ENDTABLE_KEY> tags) should be printed at the foot of 
the table. The table key is printed only if the <TABLE_KEYREF> tag appears 
in the table. 


When the table is a multipage table, the table key can be printed at the foot 
of any or all portions of the table. 


If you want the table key printed at the foot of all portions of a multipage 
table, place the <TABLE_KEYREF> tag at the end of the argument list to the 
<TABLE_HEADS> tag that defines the table’s column headings. This will 
cause the table key to be repeated on each page of the table. 


If the table key is to be printed only on specified pages of a multipage table, 
place the <TABLE_KEYREF> tag in the <TABLE_ROW> tags in the reference to 
the table key. 





EXAMPLE 


See the example under the discussion of the <TABLE_KEY> tag. 
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<TABLE_ROW> 


<TABLE_ROW> 


Specifies text for each column in the current table. 





FORMAT 


<TABLE_ROW?> (column-text 1[ \ column-text2| \ ...]]) 





ARGUMENTS 


related tags 


restrictions 


required 
terminator 


column-text 

Specifies text for a single column in the table row. The number of arguments 
specified to this tag is dependent on the number of columns specified for 

the table. This value is specified in the <TABLE_SETUP> tag. If the number 
of arguments to <TABLE_ROW> exceeds the number of columns currently 

in effect for the table, the excess columns are ignored. If the number of 
arguments is less than the number of columns currently in effect for the table, 
unspecified columns are output as blanks. 





6 <SPAN> 
° <RULE> 


° <TABLE_ROW_BREAK> 





Must be used in the context of a table. 


If the text in a single table row column exceeds the depth of an output page, 
the text formatter issues an error message and terminates processing. 


Page breaking of long table rows may be controlled, with additional 
restrictions, with the <VALID_-ROW_BREAK> tag. 





None. 





DESCRIPTION The <TABLE_ROW> tag specifies text for each column in the current table. 
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<TABLE_ROW> 





EXAMPLE 


<REFERENCE>(express_modes_tab) summarizes 
the rules for determining the mode of an expression. 


<TABLE>(Rules for Determining Expression Modes\express_modes_tab) 
<TABLE_ATTRIBUTES> (MULTIPAGE) 
<TABLE_SETUP> (2\43) 
<TABLE_HEADS>(Expression\Value Type) 
<TABLE_ROW>(Integer value\Integer) 
<TABLE_ROW>(String value\String) 
<TABLE_ROW>(Integer lexical function\Integer) 
<TABLE_ROW> (String lexical function\String) 
<TABLE_ROW> (Integer symbol\Integer) 
<TABLE_ROW> (String symbol\String) 
<TABLE_ROW>(Any value .AND. or .OR. any value\Integer) 
<TABLE_ROW>(Any value\Integer) 
<TABLE_ROW>(Any value\Integer) 

<ENDTABLE> 


This example shows how to produce a two-column table. This example may 
produce the following output: 


Table x—x summarizes the rules for determining the mode of an expression. 


Table x—x Rules for Determining Expression Modes 








Expression . Value Type 
Integer value Integer 
String value String 
Integer lexical function Integer 
String lexical function String 
Integer symbol Integer 
String symbol String 

Any value .AND. or .OR. any value Integer 

Any value Integer 

Any value Integer 
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<TABLE_ROW_BREAK> 


<TABLE_ROW_BREAK> 


Specifies the boundaries within which a long table can be broken onto a 
new page. 








FORMAT <TABLE_ROW_BREAK> ({ FIRST | ) 
LAST 
ARGUMENTS FIRST 
LAST 


related tags 


restrictions 


required 
terminator 


Specifies the bounds within which a multipage table may be broken. After 
<TABLE_ROW_BREAK> (FIRST) is specified, any row in the table up to the 
occurrence of <TABLE_ROW_BREAK> (LAST) is treated as a suitable page- 
breaking point. 





. <NESTED_TABLE_BREAK> 


: <VALID_TABLE_ROW_BREAK > 





The <TABLE_ROW_BREAK> tag is invalid in a table specified with the KEEP 
option, or in a table that is specified in an argument to a <TABLE_ROW> tag. 





None. 


DESCRIPTION 
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The <TABLE_ROW_BREAK> tag provides an allowable place for a long table to 
be broken across pages. 


Tables in VAX DOCUMENT are, by default, multipage tables. If 
<TABLE_ROW_BREAK> is not specified to provide the text formatter with 
reasonable guidelines to break tables across pages, the text formatter will 
nonetheless select page breaks. The page breaks selected will not always be 
suitable. Therefore, use of the <TABLE_ROW_BREAK> tag is recommended. 


By default, the text formatter will not break a page within a table row. With 
some restrictions, valid page breaks within table rows can be specified using 
<VALID_TABLE_ROW_BREAK> . 


Nested tables (that is, tables that are specified within an argument to a 
<TABLE_ROW> tag) can, with some restrictions, be given valid page breaks 
using the <NESTED_TABLE_BREAK> tag. 


<TABLE_ROW_BREAK> 





EXAMPLE 


<P> An expression can evaluate to either an integer or 

a string value, depending on the types of values used in the expression 
and the operations used to manipulate them. 

Table <REFERENCE>(express_modes_tab) summarizes 

the rules for determining the mode of an expression. 


<TABLE>(Rules for Determining Expression Modes\express_modes_tab) 
<TABLE_ATTRIBUTES> (MULTIPAGE) 
<TABLE_SETUP> (2\43) 
<TABLE_HEADS>(Expression\Value Type) 
<TABLE_ROW>(Integer value\Integer) 
<TABLE_ROW> (String value\String) 
<TABLE_ROW>(Integer lexical function\Integer) 
<TABLE_ROW>(String lexical function\String) 
<TABLE_ROW>(Integer symbol\Integer) 
<TABLE_ROW> (String symbol\String) 
<TABLE_ROW>(Any value .AND. or .OR. any value\Integer) 
<TABLE_ROW>(Any value\Integer) 


<COMMENT> (OK to break after this) 
<TABLE_ROW_BREAK> (first) 
<TABLE_ROW>(Any value\Integer) 
<TABLE_ROW>(Integer value\Integer) 
<TABLE_ROW> (String value\String) 
<TABLE_ROW>(Integer lexical function\Integer) 
<TABLE_ROW> (String lexical function\String) 

<COMMENT> (Don't break after this) 
<TABLE_ROW_BREAK> (last) 


<TABLE_ROW>(Integer symbol\Integer) 

<TABLE_ROW>(String symbol\String) 

<TABLE_ROW>(Any value .AND. or .OR. any value\Integer) 
<TABLE_ROW>(Any value\Integer) 

<TABLE_ROW>(Any value\Integer) 


<ENDTABLE> 


This example shows how to produce a two-column table. This example may 
produce the following output: 


An expression can evaluate to either an integer or a string value, depending 
on the types of values used in the expression and the operations used to 
manipulate them. Table x—x summarizes the rules for determining the mode 
of an expression. 


Table x—x Rules for Determining Expression Modes 








Expression Value Type 
Integer value Integer 
String value String 
Integer lexical function Integer 
String lexical function String 
Integer symbol Integer 
String symbol String 

Any value .AND. or .OR. any value Integer 

Any value Integer 

Any value Integer 
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<TABLE_ROW_BREAK> 


Table x—x (Cont.) Rules for Determining Expression Modes 


Expression Value Type 
Integer value Integer 
String value String 
Integer lexical function Integer 
String lexical function String 
Integer symbol Integer 
String symbol String 

Any value .AND. or .OR. any value Integer 

Any value Integer 

Any value Integer 
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<TABLE_SETUP> 


<TABLE_SETUP> 


Declares the number of columns in a table and the effective (approximate) 
width values to be assigned to each column. 





FORMAT 


<TABLE_SETUP> (number \ width,[.. . 
\ Widthaumber—11) 





ARGUMENTS 


related tags 


restrictions 


required 
terminator 


number 
Specifies the number of columns in the table. The argument must be a 
numeric argument in the range of 2 through 9. 


~. Number—1 ; 
Specify the approximate widths of columns 1 through number — 1. The last 


column, whose width is unspecified, uses the balance of the right-hand side 
of the page of output. 


The width unit is measured in characters. However, this is an approximante 
measurement because the width of each character depends on the fonts being 
used in the doctype. You may need to modify the width argument after 
processing the table and viewing the output. 





s <TABLE_ATTRIBUTES > 





The <TABLE_SETUP> tag must be used in the context of a table. 


If <TABLE_SETUP> is omitted from a sequence of <TABLE> tags, no table 
will be included in your output. 


The <TABLE_SETUP> tag must be placed after the <TABLE_ATTRIBUTES> 
tag and before the <TABLE_ROW> tags in the table tag sequence. 





None. 





DESCRIPTION 


The arguments to this tag define the number of columns in a multicolumn 
table and the approximate width of each column. A table can have a 
maximum of nine columns. 


In the width argument, define the width of each column except the last. This 
last column width is supplied automatically. 


Values specified in <TABLE_SETUP> are checked during processing to 

determine whether the values specified exceed or approach the table’s 

threshold for the given document type. Warning or error messages are 
issued as appropriate. 
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<TABLE_SETUP> 


If the table-column widths do not allow the table to fit within the page width, 
the text processor substitutes a smaller point size for the font in which the 
table is set. It then makes another attempt to fit the table within the text 
margin. 





EXAMPLE 


<TABLE>(Names of Cheeses from around the world\cheeses_tab) 
<TABLE_ATTRIBUTES> (wide\multipage) 

<TABLE_SETUP> (4\14\14\14) 

<TABLE_HEADS>(Cheese Name\Location of production\Type\Color) 
<TABLE_ROW>(Spreadable\Great Britain\Curdled\White) 
<TABLE_ROW>(Smooth\Switzerland\Aged and Tasty\Off yellow) 
<TABLE_ROW> (Chunky \American\Bland\Yellow) 

<ENDTABLE> 


This example may produce the following output: 


Table x—x Names of Cheeses from around the world 


Location of 


Cheese Name . production Type Color 
Spreadable Great Britain Curdled White 
Smooth Switzerland Aged and Tasty Off yellow 
Chunky American Bland Yellow 
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<TABLE_SPACE> 


<TABLE_SPACE> 


Marks the space required for a table that will be pasted in during final 
production. 





FORMAT <TABLE_SPACE> (value\text) 





ARGUMENTS value 


Specifies the amount of vertical space to be left on the page, specified in picas. 


text 

Specifies text that describes the status of the table (“To Be Set,” an art file 
number, or some other note). The text will be output in the middle of the 
space left for the table. 











related tags None. 

restrictions Must be used inside a <TABLE_ROW> tag. 
required None. 

terminator 


DESCRIPTION The <TABLE_SPACE> tag causes a blank space to be left in a table that will 
be pasted in by hand during final production. The value in the <TABLE_ 
SPACE> tag should be specified in picas, a scale used by typesetters. There 
are approximately six picas to the inch. Thus, if the table to be pasted in is 
four inches high, you should specify 24 picas. If you do not specify a value, a 
default value of eight picas is used. 


If you specify some descriptive text in the second argument, that text is output 
in the middle of the space left for the table. 





EXAMPLE 


<TABLE> (Script Control Blocks\script_tab) 
<TABLE_SETUP> (2\22) 
<TABLE_HEADS> (Block ID\Layout) 
<TABLE_ROW>(SCBEG; starts the scripting 
sequence\<TABLE_SPACE>(4\SCBEG diagram) ) 


<TABLE_ROW>(SCMID; gives the body of the script\<TABLE_SPACE>(4\SCMID 
diagram) ) 


<TABLE_ROW>(SCEND; ends the scripting sequence\<TABLE_SPACE>(4\SCEND 
diagram) ) 
<ENDTABLE> 


<TABLE_SPACE> 


This example shows how a table is coded with the <TABLE_SPACE> tag. In 
this example, the <TABLE_SPACE> tags reserve space inside of each table row 
for three separate diagrams. 


Table x—x Script Control Blocks 


Block ID Layout 


SCBEG; starts the scripting 
sequence 


SCBEG diagram 


SCMID; gives the body of the 
script 


SCMID diagram 


SCEND; ends the scripting 
sequence 


SCEND diagram 
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<TABLE_UNIT> 





<TABLE_UNIT > 


Begins a portion of a table containing rows that are to be grouped as 
logical units. 





FORMAT <TABLE_UNIT> 





ARGUMENTS = None. 








related tags ¢ — <TABLE_UNIT_HEADS> 
restrictions Can be used only within the context of a table established with the <TABLE> 
tag. 


The table must not be declared with the KEEP argument. 


If table units are long and you want to allow them to break across pages, you 
must use the <TABLE_ROW_BREAK> (first) and <TABLE_ROW_BREAK> (last) tags 
within the bounds of <TABLE_UNIT> and <ENDTABLE_UNIT> . 





required <ENDTABLE_UNIT> 
terminator 





DESCRIPTION The <TABLE_UNIT> tag and its terminating tag, <ENDTABLE_UNIT> , are 
used to subdivide a table by grouping some number of rows of the table into 
a unit. The table unit can be given a heading. 


EXAMPLE 


<Table>(String Passing Techniques Used by the Run-Time Library\Str_Tech_Tab) 
<X>(String Passing Techniques Used by the Run-Time Library)<comment>(*) 
<TABLE_ATTRIBUTES> (WIDE\MULTIPAGE) 

<Table_Setup>(4\20\7\10) 

<Table_Heads>(\<SPAN>(3)String Descriptor Fields<RULE>) 

<Table_Heads>(String Type\Class\Length\Pointer) 


<Table_Unit> 

<Table_Unit_Heads>(<SPAN>(4\LEFT) Input Argument to Procedures) 
<Table_Row>(Input string passed by descriptor \Read\Read\Read) 
<Endtable_Unit> 


<Table_Unit> 

<Table_Unit_Heads>(<SPAN>(4\LEFT) Output Argument from Procedures; 

Called Procedure Assumes the Descriptor Class) 

<Table_Row>(Output string passed by descriptor, 
fixed-length\Ignored\Read\Read) 

<Table_Row>(Qutput string passed by descriptor, dynamic\Ignored\Read, may be 
modified\Read, may be modified) 

<Endtable_Unit> 


<TABLE_UNIT> 


<Table_Unit> 

<Table_Unit_Heads>(<SPAN>(4)Output Argument from Procedures, Calling Program 
Specifies the Descriptor Class in the Descriptor) 

<Table_Row>(Output string, fixed-length ---DSC$K_CLASS = S, Z, A, NCA, SD 
\Read\Read\Read) 

<Table_Row>(Output string, dynamic ---DSC$K_CLASS_D 

\Read\Read, may be modified\Read, may be modified) 

<Table_Row>(Output string, varying-length ---DSC$K_CLASS_VS 

\Read\MAXSTRLEN is read; CURLEN is modified\Read) 

<Endtable_Unit> 


<Endtable> 


This example produces the following output: 


Table x —x String Passing Techniques Used by the Run-Time Library 





String Descriptor Fields 


String Type Class Length Pointer 
Input Argument to Procedures 

Input string passed by Read Read Read 
descriptor 


Output Argument from Procedures; Called Procedure Assumes the Descriptor Class 


Output string passed by Ignored Read Read 

descriptor, fixed-length 

Output string passed by Ignored Read, may be Read, may be modified 
descriptor, dynamic modified 


Output Argument from Procedures, Calling Program Specifies the Descriptor Class in the Descriptor 


Output string, fixed-length Read Read Read 
—DSC$K_CLASS = S, Z, 
A, NCA, SD 
Output string, dynamic Read Read, may be’ Read, may be modified 
—DSC$K_CLASS_D modified 
Output string, varying- Read MAXSTRLEN Read 
length —DSC$K_CLASS_ is read; 
VS CURLEN is 
modified 
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<TABLE_UNIT_HEADS> 


<TABLE_UNIT_HEADS> 


Specifies headings to be used for a table unit. 





FORMAT 


<TABLE_UNIT_HEADS> (col-heading| \ col-heading...]) 





ARGUMENTS 


related tags 


col-heading 

Specifies the text for the heading for each column; the first argument is 
the heading for the first column. Up to nine arguments can be specified, 
depending on the number of columns in the table. 





Ad <TABLE_UNIT> 
s <SPAN> 


. <RULE> 











restrictions Can be used only within the context of a table unit established with the 
<TABLE_UNIT> tag. 
Must immediately follow the <TABLE_UNIT> tag. 

required None. 

terminator 

DESCRIPTION The <TABLE_UNIT_HEADS> tag specifies column headings for each column 


of the table. The number of column headings depends on the number of 
columns in the table, as determined by the tag <TABLE_SETUP> . 


Often, the heading for a table unit is used to supply a single heading that 
spans the columns of the table and serves to label the table unit, rather than 
the individual columns. In this case, an argument is supplied that begins with 
the <SPAN> tag. 


A null argument leaves the corresponding table column blank. 


Notice that more than one <TABLE_UNIT_HEADS> tag can be supplied 
following a <TABLE_UNIT> tag. 
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<TABLE_UNIT_HEADS> 


When the heading text for a table column requires multiple lines, you can do 
the following: 


e Supply the text as a long argument to a single <TABLE_UNIT_HEADS> 
tag. The text is automatically displayed on the required number of lines. 


¢ Supply the text of the heading as shorter arguments to successive 
<TABLE_UNIT_HEADS> tags. In this way, you can control how the 
text is displayed on successive lines of the heading. 


If a page break occurs in the table unit, all lines of the table unit heading are 
repeated at the top of the next page. 





EXAMPLE 
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See the example in the description of the <TABLE_UNIT> tag. 


<TAG> 


<TAG> 


Labels a tag. 





FORMAT <TAG> (tag-name | \ tag-arg [ \ tag-arg]]) 





ARGUMENTS _ tag-name 


Specifies the name of the tag. 


tag-arg 


Specifies arguments to the tag. 











related tags ¢ <LITERAL> 
restrictions Invalid in math. 
required None. 
terminator 





DESCRIPTION The <tTAc> places angle brackets (<...>) around any text and 
optionally creates an argument for the specified tag. For example, when 
<TAG> (newtag\new_argument) is placed in an SDML file it produces 
<NEWTAG> (new_argument) in the output but is not evaluated as a tag. 





EXAMPLES 


<P>You use the <TAG>(p) tag to begin a new paragraph. 


This example may produce the following output: 


You use the <P> tag to begin a new paragraph. 


Use <TAG>(code_example\WIDE) if your example 
has long lines. 


© 


This example may produce the following output: 


Use <CODE_EXAMPLE> (WIDE) if your example has long lines. 


A writer can use the <tag>(line_art) tag to label a rough sketch. A writer 
should not use the <literal><icon><endliteral> tag for that purpose. 


|G) 


This example shows the difference in output caused by <TAG> and 
<LITERAL> : A writer can use the <LINE_ART> tag to label a rough sketch. 
A writer should not use the <icon> tag for that purpose. 
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<TITLE> 


<TITLE> 


Labels the title used on either a title page or part page. 





FORMAT 


<TITLE> (title-text-1[ \ title-text-2[ \ title-text-3]]) 





ARGUMENTS 


related tags 


restrictions 


required 
terminator 


title-text-n 
Specifies the 1 to 3 lines of text for the title. 





° <TITLE_PAGE> 


° <PART_PAGE> 





May only be used in the context of a <PART_PAGE> tag. 
Must be preceded by <TITLE_PAGE> . 


Accepts only two title-text arguments when used in the 
SOFTWARE.BROCHURE doctype. 





None. 


DESCRIPTION 


The <TITLE> tag labels the title to appear on a title page or part page. It 
accepts arguments for one to three lines of title-text in all doctypes except 
SOFTWARE.BROCHURE. 


In the SOFTWARE.BROCHURE doctype, the <TITLE> tag accepts one or two 
title-text arguments. If only the first argument is specified, that title text is 
placed at the top of the first page and at the bottom of each successive page; 
if the optional second argument is also specified, that title text is placed at 
the bottom of each page. The title text placed at the bottom of the page by 
the SOFTWARE.BROCHURE <TITLE> tag will be overridden by the text 
argument of any subsequent <CHAPTER> tags. 





EXAMPLE 
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See the example in the <PART_PAGE> tag description. 


<TITLE_PAGE> 


<TITLE_PAGE> 


Labels the beginning of a title page and enables the title page tags. 





FORMAT <TITLE_PAGE> 





ARGUMENTS = None. 





related tags None. 





restrictions This tag must be used in the context of a <FRONT_MATTER> tag. 


If you are using a preface, the title page must be terminated before the 
<PREFACE> tag. 





required <ENDTITLE_PAGE> 
terminator 





DESCRIPTION The following title page tags are enabled by the <TITLE_PAGE> tag: 
°¢ <TITLE> 
¢ = <ORDER_NUMBER> 
. <ABSTRACT> 


is <REVISION_INFO> 





EXAMPLE See the example in the <FRONT_MATTER> tag description. 
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<U> 


<U> 


Labels the user portion of a dialog between user and system in an 
interactive example. 





FORMAT 


<U> (text) 





ARGUMENTS 


related tags 


restrictions 


required 
terminator 


text 
Specifies the text of the user input. 





. <INTERACTIVE> 


<S> 





None. 





None. 





DESCRIPTION 


The <u> tag labels the user portion of a dialog between the system and 

a user. An example containing this type of dialog needs to have both parts 
identified in order to differentiate the two types of text in the source code, the 
output, or both. 


The <U> and <S> tags are also used to differentiate the system and user 
text inside of examples created with the <EXAMPLE_SEQUENCE> and <EXI> 
tags, in the SOFTWARE doctype. For more information on this doctype, refer 
to the VAX DOCUMENT User Manual, Volume 2. 





EXAMPLES 


<P>The following example of VAXMAIL contains messages from both 


the system and a user of the system: 


<INTERACTIVE> 
<U> (mail) 


<S>(MAIL> )<U>(send) 


<S>(To: )<U>(nodename: : Courtney) 
<S> (,MAIL-E-NOSUCHUSR, no such user COURTNEY at node NODENAME) 


<ENDINTERACTIVE> 


This example may produce the following output: 


The following example of VAXMAIL contains messages from both the system 
and a user of the system: 


mail 

MAIL> send 

To: nodename: :Courtney 

“%#MAIL-E-NOSUCHUSR, no such user COURTNEY at node NODENAME 


<UNDERLINE> 


<UNDERLINE> 


Marks a portion of text to be underlined. 





FORMAT <UNDERLINE> (text) 
or 


<UNDERLINE> 
text 


<ENDUNDERLINE> 





ARGUMENTS text 


Specifies the text string to be underlined. 





related tags None. 





restrictions Because the text string that is marked for underlining will be kept on the 
same line in the output, do not make the underline longer than the page 
width or errors might be generated. 





required <ENDUNDERLINE> — Required if the text is not passed as an argument. 
terminator 


EXAMPLE 


<P>If you use the appropriate flags, your output 

may look like this: 

<P> 

<SAMPLE_TEXT> 

<UNDERLINE>(The Decline and Fall of the Roman Empire) 
<ENDSAMPLE_TEXT> 





This example may produce the following output: 


If you use the appropriate flags, your output may look like this: 


The Decline and Fall of the Roman Empire 
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<UPDATE_RANGE> 


<UPDATE_RANGE> 


Marks the location at which a new section of updated pages begins. 





FORMAT 


<UPDATE—RANGE > (start-page \ end-page) 





ARGUMENTS 


related tags 


restrictions 


required 
terminator 


start-page 
Specifies the page number from the printed documentation of the first page 
that must be printed. This must be an odd-numbered page. 


end-page 

Specifies either the last page to be included in a set of update pages or 
the keyword EOF. If end-page is a number, that number must be an 

even number. The text formatter output routines that handle updates will 
automatically generate point-numbered pages if text within the bounds of 
start-page and end-page will not fit within those pages. If EOF is specified, 
then the update range continues to the end of a chapter or section. 





° <REVISION> 


® <MARK> 





Must be used in the context of the <REVISION> tag, and <REVISION> must 
specify the keyword UPDATE. If the <REVISION> tag is not specified, then 
the <UPDATE_RANGE> and <ENDUPDATE_RANGE> tags are nonoperational; 
that is, no output will be generated from these tags when the file is processed. 





<ENDUPDATE_RANGE> 





DESCRIPTION Files coded with the <REVISION> (UPDATE\update-level) tag and containing 
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<UPDATE_RANGE> tags will process as follows: 


When the text formatter processes a file that has been marked as an 
update, it processes all text and commands in the file, but does not 
produce actual output for the DVI file except for those pages marked 
within an update range. 


When the text formatter reaches the beginning of an update range, it 
sets the page number to the page number specified as the start of the 
update. Therefore, it is not important that previous versions of the text 
formatter file were modified for pagination during final production. All 
pages processed outside of an update range are not output. 


<UPDATE_RANGE> 


The following rules apply to the placement of the <UPDATE_RANGE> tag: 


e If the text on the first update page is in the middle of a text element 
(for example, a paragraph, a list element, a code example), then the 
<UPDATE_RANGE> tag must precede the word of text that is the first 
word on the page. 


e If the text on the first update page represents the beginning of a new text 
element (<P>, <LIST>, <LE>, <CODE_EXAMPLE> , and so on), the 
<UPDATE_RANGE> tag must be placed immediately preceding the tag for 
the text element. 


e If an update range begins on a page that starts with a continued table, 
the file must specify the start of the update range on the odd-numbered 
page preceding the beginning of that table, or (if the table begins on an 
odd-numbered page) the page on which the table begins. If these pages 
are not to be a part of the update, they may be discarded. 


e If one or more pages before an update range begins contains 
a floating figure or example, the <FIGURE_ATTRIBUTES> or 
<EXAMPLE_ATTRIBUTES> tags must be modified to specify KEEP. This 
will prevent the text formatter from floating the figure or example to the 
top of the first update page. 


Put a <COMMENT> tag in the file to indicate that the modification was 
made for the purposes of the update only. For example: 


<COMMENT>(KEEP added to example for update only...) 


When the file is subsequently revised, the KEEP arguments can be 
removed. 


¢ When a file that contains the <REVISION> (UPDATE) tag is processed, the 
table of contents and index are handled as follows: 


e If the <CONTENTS_FILE> or <INDEX_FILE> tag occurs between 
the bounds of <UPDATE_RANGE> and <ENDUPDATE_RANGE> , and 
/CONTENTS or /INDEX is specified on the command line, the 
contents file or index file is included within the pages for the update 
range. 


e If the <CONTENTS_FILE> or <INDEX_FILE> tag occurs in the file 
but is specified outside the bounds of <UPDATE_RANGE> and 
<ENDUPDATE_RANGE> tags, and if /CONTENTS or /INDEX is 
specified on the command line, the table of contents file or index file 
is included in the output file. 
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<UPDATE_RANGE> 





EXAMPLE 


<REVISION>(UPDATE\July 1986) 


<UPDATE_RANGE> (5\24) 
<P> 


The first sentence on page 5 goes here. 


20 or more pages of modified text goes here. 


The last sentence on page 24.n goes here. 


<ENDUPDATE_RANGE> 
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In this example, the updated material begins on page 5 and continues through 
page 24. When page 24 is reached, the page numbering becomes 24.1, 24.2, 
etc., until the end of the update range is reached. The <ENDUPDATE_RANGE> 
tag must be placed in the source file at the position corresponding to the place 
at which an update sequence ends. 


<UPPERCASE> 


<UPPERCASE> 


Labels text that should appear as uppercase in the final output. 





FORMAT 


<UPPERCASE> (text) 





ARGUMENTS 


related tags 


text 
Specifies the text to appear in uppercase. 





° <LOWERCASE> 














restrictions None. 

required None. 

terminator 

DESCRIPTION If your book contains a text element, such as a heading, that normally appears 
in lowercase, you may encounter a situation where you need to overcome the 
default case in one of your tags and ensure that the result in the final output 
appears in uppercase. The <UPPERCASE> tag allows you to do this. 

EXAMPLE 


<HEAD2>(here is an example of <UPPERCASE>(uppercase) text) 


In this example, assume that the doctype being used causes the tag <HEAD2> 
to output a heading that is in lowercase, no matter what the case of the text 
passed to it. The <UPPERCASE> tag overrides the default in this <HEAD2> 
tag. This example produces the following output: 


here is an example of UPPERCASE text 
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<USER_I_MESSAGE> 


<USER_I_MESSAGE> 


Sends an informational message to the terminal or log file during 
processing of a file. 





FORMAT 


<USER_I_MESSAGE > (text) 





ARGUMENTS 


related tags 


restrictions 


required 
terminator 


text 
Specifies the text you wish to appear on the terminal or in the log file. 





° <USER—_W_MESSAGE> 





You must process the file with the /LOG qualifier in order to see any <USER_ 
I_MESSAGE> messages. 


The message text is limited to 150 characters. 





None. 





DESCRIPTION The <USER_I_MESSAGE> tag generates a message when the file is processed, 
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Note: 


but only when the /LOG qualifier is specified on the command line. The 
message is sent to the terminal if the file is processed interactively or to the 
log file if it is processed as a batch job. 


The messages are listed in the .LIS file if you specify the /LIST qualifier on 
the command line. 


You can use the tag to broadcast any important information that should be 
noted or flagged during tag translation; for example, you might use it as a 
reminder that a part of the file is incomplete. 


The tag translator displays the line number and the file name in which the 
tag appears. The message is output in the following format: 


%TAG-I-USER_IMSG, mmmmmmmmmmmmmmmmmmn 
Line is nnn of file fffffffffffff 


To receive any messages tagged with <USER_I_MESSAGE> tags, you must 
process the file with the /LOG qualifier on the command line. If you 
want to generate only a few messages, you might choose to use the 
<USER_W_MESSAGE> tag and not process the file with the additional 
qualifier. 


<USER_I_MESSAGE> 





EXAMPLE 


<USER_I_MESSAGE>(Section 2 is incomplete and requires 
information from Tom Jones.) 


This example shows how a <USER_I_MESSAGE> tag can be used to flag a 
section of a file that requires further work. The message would only be sent 
to the terminal if the user processed the file with the /LOG qualifier on the 
command line. If the text element containing this tag were processed as a 
batch job, the log file would contain the following entry: 


“%TAG-I-USER_IMSG, Section 2 is. incomplete and requires information 


from Tom Jones. 
Line is 68 of file part2.gnc 
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<USER_W_MESSAGE> 


<USER_W_MESSAGE> 


Sends a warning message to the terminal or log file during processing of a 
file. 





FORMAT 


<USER_W_MESSAGE> (warning-text) 





ARGUMENTS 


related tags 


warning-text 
The text you wish to appear on the terminal or in the log file. 





: <USER_I_-MESSAGE> 











restrictions The message text is limited to 150 characters. 
required None. 
terminator 
DESCRIPTION The <USER_W_MESSAGE> tag generates a message when the file is processed, 
sending it to the terminal if processed interactively or the log file if processed 
as a batch job. 
Note: This type of message is counted by the tag translator as a warning 
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message. After thirty warning messages, tag translation halts. Therefore, 
use the <USER_W_MESSAGE> tag for generating messages only if you 

are issuing few messages. For a file that contains many messages, tag 
messages with <USER_I-MESSAGE> tags and process the file with the 
/LOG qualifier. 


You can use it to flag any important information that should be noted during 
processing; for example, you might use it as a reminder that a part of the file 
is incomplete. Whatever message you enter as an argument to the <USER_W_ 
MESSAGE> tag is written to the terminal or to the batch log file when the text 
element that contains it is processed through the tag translator. 


The tag translator displays the line number and the file name in which the 
<USER_W_MESSAGE> tag appears. The message is output in the following 
format: 


4TAG-W-USER_WMSG, at tag <USER_W_MESSAGE> on line nnn of file 
fffffiff 
NMMnMMMMMMMMMMMMMMMMmmmmmmnmn 


The messages are listed in the .LIS file if you specify the /LIST qualifier on 
the command line. 


<USER_W_MESSAGE> 





EXAMPLE 


<USER_W_MESSAGE>(Reviewers: Please note missing parameters here.) 


This example shows how the <USER_W_MESSAGE> tag is used to identify 

a notice in a file. If the file containing this message was called “Reviewers_ 
copy.SDML,” and it was processed as a batch job, the log file wquld contain 
the following entry: 


“4TAG-W-USER_WMSG, at tag USER_W_MESSAGE on line nn of file 


Reviewers_copy.SDML. 
Reviewers: Please note missing parameters here. 
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<VALID_BREAK> 


<VALID_BREAK> 


Labels a permissible page break within a monospaced example. 





FORMAT <VALID_BREAK> 





ARGUMENTS = None. 








related tags ° = <CODE_EXAMPLE> 
e  <DISPLAY> 
¢  <INTERACTIVE> 
®  <LINE_ART> 
restrictions This tag can be used only within monospaced examples created using the 


<CODE_EXAMPLE> , <DISPLAY> , <INTERACTIVE>, or <LINE_ART> tags. 





required None. 
terminator 





DESCRIPTION The text formatter attempts to keep an example together on a single page. 
If there is not enough room for an example on the current page, the text 
formatter chooses page breaks using blank lines in the example as “good” 
places to break. If your example contains no blank lines, or if you want to 
specify better breaking points, you can use <VALID_BREAK> to specify the 
places that are acceptable page breaks. 





EXAMPLE 


<INTERACTIVE> 


<S>($) 
<U> (@SYS$SYSTEM : SHUTDOWN) 


<S>( SHUTDOWN -- Perform an Orderly System Shutdown) 
<ELLIPSIS> 

<S>(CENTRAL, PRINTER, TAPES, DISKS, DEVICES, CARDS, NETWORK, OPER1) 
<S>(OPER3, OPER4, OPER5S, OPER6, OPER7, OPER8, OPER9, OPER10O, OPER11,) 
<S>(OPER12) 

<VALID_BREAK> 


<S>(%SHUTDOWN-I-DISLOGINS, Interactive logins will now be disabled.) 
<S>(%SET-I-INTSET, login interactive limit = O current interactive value = 17) 
<S>(%SHUTDOWN-I-SHUTNET, The DECnet network will now be shut down.) 
<S>(%SHUTDOWN-I-STOPQUEMAN, The queue manager will now be stopped.) 
<ENDINTERACTIVE> 


This example shows the use of the <VALID_BREAK> tag. 


<VALID_TABLE_ROW_BREAK> 


<VALID_TABLE_ROW_BREAK> 


Marks a permissible place that a first-level table row may be broken across 
pages. 





FORMAT 


<VALID_TABLE_ROW_BREAK> 





ARGUMENTS 


related tags 


restrictions 


required 
terminator 


None. 





e <NESTED_TABLE_BREAK> 





This tag must be used in the context of a table. May only be used in the last 
column of a 2- or 3-column, first-level table. That is, this tag may not be 
specified in a table that is specified inside a <TABLE_ROW> tag. 





None. 





DESCRIPTION 


The <VALID_TABLE_ROW_BREAK> tag provides an allowable place for 

a long table column to be broken across a page. If you do not use the 
<VALID_TABLE_ROW_BREAK> tag inside a long table row, the text formatter 
tries to keep all the text on the same page of output and might issue a PAGE- 
TOO-LONG error message. In extreme cases, the text formatter could run out 
of memory trying to process the table row and terminate processing. 





EXAMPLE 


<TABLE> 


<TABLE_ATTRIBUTES> (MULTIPAGE) 


<TABLE_SETUP>(2\9) 


<TABLE_ROW> (Item\Text that goes on for several paragraphs. 


<VALID_TABLE_ROW_BREAK> 


Text that is still inside the first table row. 


<P> 
<VALID_TABLE_ROW_BREAK> 


The last paragraphs for this table row.) 


<ENDTABLE> 


This example shows the use of the <VALID_TABLE_ROW_BREAK> tag in a table 
with a long row. 
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<VARIABLE> 


<VARIABLE> 


Labels a program variable or number. 





FORMAT <VARIABLE> (variable-name) 





ARGUMENTS _ variable-name 


Specifies the name of the variable to be typographically distinguished. 











related tags ¢ = <KEYWORD> 
restrictions None. 
required None. 
terminator 





DESCRIPTION The <VARIABLE> tag names a variable discussed in text. Use of the 
<VARIABLE> tag and its result in formatted text must be agreed upon by 
writer, editor, and book designer. Above all, you should seek a consistent 
usage within a document and across a document set. 





EXAMPLE 


<P>At this point in the processing, 
<VARIABLE> (NUMBER_OF_JELLYBEANS) has the 

value 

of 2. 


This example may produce the following output: 


At this point in the processing, NUMBER_.OF_JELLYBEANS has the value of 
2. 
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<VBAR> 


<VBAR> 


Labels an occurrence of a vertical bar in an argument to a tag. 





FORMAT <VBAR> 





ARGUMENTS = None. 











related tags e The following tags label other characters that must be tagged when they 
occur in an argument to a global tag: 
<AMPERSAND> 
<BACKSLASH > 
<CPAREN > 
<OPAREN > 
restrictions Can only be used within an argument to a tag. 
required _ None. 
terminator 





DESCRIPTION The tag translator uses a vertical bar (!) to begin a quoted string. An 
ampersand concludes a quoted string. If you use a literal vertical bar within 
an argument to an SDML tag, the tag translator reads the vertical bar as 
beginning a section of text it should treat literally. The vertical bar may 
prevent the tag translator from evaluating a tag when it should and may 
cause an error in your output. 


To process a vertical bar in an argument to a tag (through to your output), 
use the <VBAR> tag. 





EXAMPLE 


<SUBHEAD1>(Labeling the Vertical Bar (<VBAR>) Within Your 

Code) 

<P>To pass a vertical bar (|) in an argument to a tag through 

to your output, 
This example produces the following output: 
Labeling the Vertical Bar (|) Within Your Code 


To pass a vertical bar (1) in an argument to a tag through to your output, ... 
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<X> 


<X> 


Creates an index entry with a reference to the page on which this tag 


appears. 





FORMAT <X> (index-entry| \ attribute]) 





ARGUMENTS _ index-entry 


Specifies the index entry to appear in the index. The capitalization you use in 
this string will be the capitalization that appears in the index. 


Use the <XSUBENTRY> tag to separate the main entry from the first subentry, 
if used, and the second subentry from the first, as follows: 


<x> (main entry <xsuBenTRY> subentry <xSUBENTRY> Subentry) 


You should use no more than two levels of subentries in a book index. 


attribute 


Specifies the attributes that control the sorting and formatting of the index 
entry. You can specify a maximum of five attribute arguments from among 
the following possibilities. Each attribute must be passed as a separate 


argument. 


Attribute 
<XAPPEND> (string) 


BEGIN 


BOLD 


END 


ITALIC 
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Function 


Causes the indexing software to append the specified 
string to the page reference in the index. 


Causes the indexing program to begin a page-range 
reference. When you use this attribute, you must pair it 
with a following <X> _ tag that has identical text and the 
END attribute. 


Causes the page reference number to appear in boldface. 
This is distinct from any boldfacing that appears in the 
text of the index entry itself. 


Causes the index program to end a page-range reference. 
When you use this attribute, you must pair it with a 
previous <X> tag that has identical text and the BEGIN 
attribute. 


Causes page reference numbers to appear in italic type in 
your index entry. If both BOLD and ITALIC are specified, 
the entry is output in bold italic type. Entries that use the 
ITALIC attribute are sorted as being distinct from entries 
that are output in an italic type face using some other 
means (such as the global <EMPHASIS> tag). 


related tags 


restrictions 


required 
terminator 


Attribute Function 
MASTER Causes the index program to insert the entry only in the 


master index. By default, the entries are inserted only 
in the local index. This attribute allows you to specify 
different entries for a book’s local index and for the 
master index of the document set. 


<XSORT> (string) Causes the index program to use the specified string as 
the sort key when placing this entry in the index. Use 
this attribute to override the sorting algorithm of the index 
utility for single index entries (for example, to force an 
entry with a leading nonalphanumeric character to the top 
of the index). 





e <y>-—Used for entering a cross-reference index entry 





Do not place <x> tags within any kind of example. Doing so will interfere 
with the formatting of the example. 


Be sure <X> tags follow headings, commands, and other major text elements 
that are likely to begin a new page. 


In tables, place <xX> tags directly next to the items to be indexed. In doing 
so, the <X> tag will be included within the argument string for table tags 
such as <TABLE_ROW> or <TABLE _HEADS> . 





None. 





DESCRIPTION 


The <x> tag creates an entry in the index to the book. The entry is 
composed of the main entry and optional subentries specified in the first 
argument to the tag. 


You can control how the index entry is sorted and how it appears by 
specifying particular attributes. 


For instance, the <XAPPEND> attribute is useful when appending text to 
the end of a page reference, as when referring to an example (5-4ex) or to a 
table (9-8tab). The <XAPPEND> attribute can also be used for such common 
indexing terms as “page 3ff”’ or “5-3 to 5-6 passim.” 


The appended string is boldfaced or italicized if its page reference is boldfaced 
or italicized. BOLD and ITALIC can be used together. 


You can create an index entry for several inclusive pages by using the BEGIN 
and END attributes. When using a BEGIN and END pair, you must be certain 
that the index entries are identical and that any other attributes you specify 


are the same for each entry, as well. 


You can specify that an index entry appear in a master index by using the 
MASTER attribute. By default, an entry appears in the master index only if 
this attribute has been specified. It is possible to override this arrangement at 
the time the master index is built and include every entry in the local index in 
the master. No entry marked with the MASTER attribute appears in the local 
index. 
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<X> 


If you have an index entry for which you want to control the sorting, you 
can do so by using the <XSORT> attribute. For example, since leading 
nonalphabetic characters are ignored by default, the main entry $SEARCH 
normally appears with other entries beginning with the letter “S.” To force 
the indexing software to place $SEARCH before the “A” section, use the 
<XSORT> attribute as follows: 


<X> ($SEARCH\<XSORT> ($) ) 


You must use the <XSORT> attribute if your main entry begins with a double 
backslash or a right angle bracket. 


The <XSUBENTRY> Tag 


You can use the <XSUBENTRY> tag within this argument to separate the 
main entry from the first subentry, and the second subentry from the first, as 
follows: 


<X> (Main entry <xsubentry> subentry-1 <xsubentry> subentry-2) 


The <XSUBENTRY> tag can be abbreviated as <xS>. Using this shorter form 
of the tag, the previous example could be expressed as follows: 


<X> (Main entry <xs> subentry-1 <xs> subentry-2) 


You can use no more than three levels of subentries in an index. 


EXAMPLES 


1 <X>(File structure\begin) 


<X>(File structure\end) 


These index tags create an inclusive page entry, and may produce the 
following output. 


File structure, 5-4 to 5-7 


2 <X>(File structure\begin) 


<X>(File structure\end\<XAPPEND>( passim) ) 


This index tag creates an index entry that may produce the following output. 


File structure, 5-4 to 5-7 passim 
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<X> 


3} <TABLE_ROW>(apples\oranges\pears) 
<TABLE_ROW>(<X>(Tropical fruits<XS>bananas) bananas\pineapples\mangos) 
<TABLE_ROW> (blackberries\blueberries\strawberries) 


The <x> tag in this example creates an index entry that will correctly 
specify the page that the text “bananas” appears on, no matter where VAX 
DOCUMENT chooses to break the table that contains “bananas.” This index 
entry may produce the following output. 


Tropical fruits 


bananas, 3-21 
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<Y> 


<Y> 


Creates an index entry with no reference to the page on which this tag 
appears. Used for cross-references (“See” or “See also” entries). 





FORMAT 


<Y> (index-entry/ \ attribute]) 





ARGUMENTS 


related tags 


restrictions 


required 
terminator 
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index-entry 

Specifies the string that supplies additional information to the main entry and 
subentries that will appear in the index. The capitalization you use in this 
string will be the capitalization that appears in the index. 


Use the <XSUBENTRY> tag to separate the main entry from the first subentry, 
and the second subentry from the first, as follows: 


Main entry <xsubentry> subentry 


You should use no more than two levels of subentries in a book index. 


attribute 


Specifies the attributes that control the sorting and formatting of the index 
entry. You can specify a maximum of two attribute arguments from among 
the following possibilities. Each attribute must be passed as a separate 
argument. 


Attribute Function 


MASTER ‘Causes the index program to insert the entry only in the 
master index. By default, the entry is inserted only in the 
local index. This attribute allows you to specify different 
entries for a book’s local index and for the master index of 
the document set. 


<XSORT > (string) Causes the index program to use the specified string as the 
sort key when placing this entry in the index. You must 
enclose the string in either double quotation marks (") or 
single quotation marks (‘). Use this attribute to override 
the sorting algorithm of the index utility for single index 
entries. 





<x? 





Do not place <Y> tags within any kind of example. Doing so will interfere 
with the formatting of the examples. 





None. 


<Y> 





~ DESCRIPTION 


The <yY> tag creates an unpaged entry in the index to the book. The entry 
that appears in the index is composed of the main entry and “See” or “See 
also” subentries specified in the first argument to the tag. 


You can control how the index entry is sorted and where it will appear by 
specifying particular attributes in arguments two through four of the <yY> 
tag. 


You can specify that an index entry appear in a master index by using the 
MASTER attribute. By default, an entry will appear in the master index only 
if this attribute has been specified. It is possible to override this arrangement 
and include every entry in the local index in the master. 


If you have an index entry for which you want to control the sorting, you 
can do so by using the <XSORT> attribute. For example, because leading 
nonalphabetic characters are ignored by default, the main entry $SEARCH 
normally appears with other entries beginning with the letter “S.” To force 
the indexing software to place $S5EARCH before the “A” section, you can use 
the SORT attribute as follows: 


<Y> ($SEARCH <XS> See System Services\ <XSORT> ($)) 





EXAMPLE 


<X>(File structure designators) 
<Y>(File structure designators<XSUBENTRY>See also Header blocks) 


This index command would create the following index entry, assuming these 
tags appeared on page 1-3: 


File stucture designators, 1-3 
See also Header blocks 
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AA VAX DOCUMENT Command Summary 


This appendix describes the DCL command line interface to VAX 
DOCUMENT. A summary of this information can be obtained by typing 
the following command once VAX DOCUMENT is installed: 


$ HELP DOCUMENT 


See Chapter 4 for tutorial information on how to process your files using the 
DOCUMENT command. 


DOCUMENT 








DOCUMENT 
Invokes the VAX DOCUMENT document production system. 
FORMAT DOCUMENT input-file-spec doctype destination 
Command Qualifier Default 
/[NO]BA TCH|=qualifier-keyword] /NOBATCH 
/CONDITION=condition-name None. 
/[NOJCONTENTS /NOCONTENTS 
/[NOJDEVICE_CONVERTER|-device-keyword] /DEVICE_CONVERTER 
/[NO]DIAGNOSTICS/=file-spec] /NODIAGNOSTICS 
/ELEMENT=file-spec None. 
/INCLUDE=file-spec None. 
_ /[NOJINDEX[=index-keyword] /NOINDEX 
/[NO]KEEP/=filetype-keyword] /NOKEEP 
/[NOJLIST[=file-spec] /NOLIST 
/[NOJLOG /LOG 
/[NO]MAP|=file-spec] /NOMAP 
/[NOJMASTER_INDEX[=index-keyword] /NOMASTER_INDEX 
/OUTPUT=file-spec See text. 
/[NO]PRINT [=qualifier-keyword] /PRINT 
/PROFILE=file-spec None. 
/[NOJSYMBOLS=file-spec /NOSYMBOLS 
/[NO]JTAG_ TRANSLATOR /TAG_TRANSLATOR 
/[NO]TEXT_FORMATTER /TEXT_FORMATTER 
restrictions None. 





PARAMETERS input-file-spec 


Specifies the input file to be processed. Note that wildcards are not allowed 
in the input file specification. 

The default file type of the input file specification expected by VAX 
DOCUMENT is SDML. If qualifiers are specified, VAX DOCUMENT 
determines the default file type based on the qualifiers and the destination 
keyword you specify. 

Table A-1 lists the default file types and the qualifiers and default 
destinations that provide them. 


Table A-1 Default File Types 


VAX DOCUMENT 


Default Destination 


DOCUMENT 


Default Input 


Qualifiers Used Keyword Used File Type 
None. Any SDML 
/TAG_TRANSLATOR Any SDML 
/NOTAG_TRANSLATOR Any TEX 
/TEXT_FORMATTER 
/NOTAG_TRANSLATOR LNO3 DVI_LNO3 
/NOTEXT_FORMATTER PS DVI_PS 
/DEVICE_CONVERTER LINE DVI_LINE 
TERMINAL DVI_LINE 
MAIL DVI_LINE 
/NOTAG_TRANSLATOR LNO3 LNO3 
/NOTEXT_FORMATTER PS PS 
/NODEVICE_CONVERTER LINE LINE 
/PRINT TERMINAL TERM 
MAIL TXT 


‘Braces in this table indicate that the enclosed qualifiers occur together on the 
command line. 


doctype 

Specifies the type of document being produced. The doctype you select on the 
command line determines the style of your output and determines the SDML 
tags you can use. Note that some tags are valid only in specific doctypes. 
See the VAX DOCUMENT User Manual, Volume 2, for more information on 
doctype-specific tags. 


All doctypes have a default design. Some doctypes have several designs. 
These doctypes accept a design keyword as part of the doctype specification. 
The design keyword specifies an alternate design within the doctype. For 
example, the SOFTWARE doctype has designs for different page sizes, 
heading level formats, and so on. 


The design keyword is specified as part of the doctype and is separated from 
the doctype keyword by a period (.). For example, the REPORT doctype 
has two alternate designs: one in which the text runs the full text page 
width (the default), and another in which the text is placed in two columns. 
You specify the default design as REPORT and the two-column design as 
REPORT.TWOCOL. You can abbreviate the doctype keyword to any unique 
string. For example, you could abbreviate REPORT.TWOCOL to REP.TWO, 
or even R.T as long as each keyword is unique. 


Table A-2 summarizes the supported VAX DOCUMENT doctype keywords 
and includes a basic use for each keyword, and a summary description of the 
available designs. See the VAX DOCUMENT Design Samples manual for more 
information on each of these doctype designs. 


DOCUMENT 


Table A-2 VAX DOCUMENT Doctypes 


Doctype Keyword 
ARTICLE 


LETTER 
MANUAL.GUIDE 
MANUAL.PRIMER 
MANUAL.REFERENCE 
MILSPEC 
OVERHEADS 


OVERHEADS.35MM 
REPORT 


REPORT.TWOCOL 


SOFTWARE.BROCHURE 


SOFTWARE.GUIDE 


SOFTWARE.HANDBOOK 


Used to Create 
Articles 


Letters or memos 


User manuals 


Military specifications 


Overhead slides for 
transparencies 


General-purpose 
documents 


User manuals 
containing detailed 
information on software 


SOFTWARE.POCKET_REFERENCE 


SOFTWARE.REFERENCE 


SOFTWARE.SPECIFICATION 


Design Description 


85 x 11 inches, numbered or unnumbered 
headings, text is placed in a two-column format 


85 x 11 inches, unnumbered headings 
7 x 9 inches, numbered headings 

7 x 9 inches, unnumbered headings 
84 x 11 inches, numbered headings 
85 x 11 inches, numbered headings 


84 x 11 inches, no headings 


65 x 53 inches, no headings 


83 x 11 inches, numbered headings 


85 x 11 inches, numbered headings, text is 
placed in a two-column format 


7 x 9 inches, unnumbered headings 


7 x 9 inches, numbered headings 

7 x 9 inches, numbered headings 
53 X 7 inches, numbered headings 
85 Xx 11 inches, numbered headings 
85 x 11 inches, numbered headings 


You can have additional local doctype keywords defined at your site. See 
your VAX DOCUMENT system administrator for information on local doctype 
keywords. 


destination | 
Specifies the output device destination keyword for the document. VAX 
DOCUMENT supports the following output destination keywords (these 
keywords are the default keywords provided when VAX DOCUMENT is 
installed, your local destination keywords may be different): 


Destination Keyword 


LINE | 
LNO3 | 
Ps! 


TERMINAL 


MAIL 


installation procedure. 


Formatted For 
A line printer 
An LNO3 laser printer 


Any Digital-supported POSTSCRIPT output device, 
such as the PRINTSERVER 40 or the LNO3R 
SCRIPTPRINTER 


A standard ANSI terminal, such as the VT-100 
Sending through the VMS Mail Utility 


‘These destinations are installed at your site only if they were selected during the 


DOCUMENT 


You can abbreviate the destination keyword to any unique string. For 
example, you could abbreviate LN03 to LNO, or even LN as long as that 
string is unique. 


You can have additional local destination keywords defined at your site. 
See your VAX DOCUMENT system administrator for information on local 
destination keywords. 





DESCRIPTION DOCUMENT is the command you specify to invoke VAX DOCUMENT. VAX 
D 


UMENT is a document production system that lets you create documents 
in many different formats for a variety of output devices. All documents are 
created by entering SDML tags into an input file which is then processed by 
VAX DOCUMENT. 


The DOCUMENT command requires three parameters: 
e Input File Specification 


Specifies the input file for VAX DOCUMENT. This file is by default an 
SDML file containing SDML tags, however, it can also be one of the 
intermediate files generated by VAX DOCUMENT. 


e Doctype 


Specifies the document type keyword for which the input file should be 
processed. This keyword specifies the kind of document to be created (a 
letter, a software manual, a journal article, and so on). 


e Destination 


Specifies the final processing destination for the input file. This keyword 
typically specifies a format used by a printer, but can specify formats for 
terminals or the VMS Mail Utility. 


You can use the qualifiers to the DOCUMENT command to create indexes, 
master indexes, tables of contents, and to modify the default processing of 
your input file. 





COMMAND 
QUALIFIERS 


/BATCH[=(qualifier-keyword[, qualifier- keyword... ])] 
/NOBATCH 


Specifies whether VAX DOCUMENT should be run interactively or submitted 
as a batch job. The default qualifier is /NOBATCH, which specifies that VAX 


~DOCUMENT should be run interactively. 


The /BATCH qualifier builds and issues a DCL SUBMIT command that 
submits a job to SYS$BATCH with a job name that has the same file name 
as the input-file-spec used on the command line, prefixed with the string 
“DOC$.” For example, the file ROUTINES.SDML would be submitted as the 
job DOC$ROUTINES. 


You can use any of the DCL SUBMIT command qualifiers with VAX 
DOCUMENT by passing these qualifiers as keywords to the /BATCH 
qualifier. For example, if you want a command procedure to be run after 
9:00 and want to be notified when it completes, you could use the following 
command: 


$ SUBMIT somefile.com /AFTER=09:00/NOTIFY 


DOCUMENT 


You can specify the same options for your document processing using the 
/BATCH qualifier on the command line as follows: 


$ DOCUMENT somefile /BATCH=(AFTER=09:00,NOTIFY) LETTER LNO3 


When you use the /BATCH qualifier, a file is created in your current default 
directory that contains information about the batch job. This file has the same 
file name as the input-file-spec used on the command line with a default file 
type of LOG. When your batch job completes, this file is printed to the queue 
defined by the logical SYS$PRINT and the file is deleted. 


Note that any process logical names you enter on the DOCUMENT command 
line must be defined in your LOGIN.COM file, otherwise VAX DOCUMENT 
will be unable to translate the logical name during batch processing and will 
issue an error message. 


/CONDITION=condition-name 


Specifies a condition keyword for a conditionalized SDML input file. Using 
this qualifier has the same effect as using the <SET_CONDITION> tag at the 
beginning of your input file. This qualifier accepts a condition-name argument 
that is a text string used to mark the condition being set. 


The /CONDITION qualifier is valid only if tag translation is being done. 
If /NOTAG_TRANSLATOR is specified with the /CONDITION qualifier, 
the /CONDITION qualifier is ignored, and VAX DOCUMENT issues an 
informational message stating that you have specified conflicting qualifiers. 


/CONTENTS 
/NOCONTENTS 


Specifies whether a table of contents file should be produced. The 
/NOCONTENTS qualifier is the default and specifies that no table of 
contents should be produced. When the /CONTENTS qualifier is specified, 
VAX DOCUMENT creates a table of contents file with a file name of 
input-filename_CONTENTS. 


If you place the <CONTENTS_FILE> tag in your SDML file and also specify 
/DEVICE_CONVERTER on the command line, the current table of contents 
file is included at the corresponding point in the final printable output 

file (filename.LNO3, filename.PS, and so on). If you do not place the 
<CONTENTS_FILE> tag in your SDML file, the table of contents is not 
incorporated into your final output file, but is placed in the separate file 
input-filename_CONTENTS and processed separately. 


The file type of this table of contents output file depends upon the destination 
keyword and the processing qualifiers you have selected on the DOCUMENT 
command line. You can use the /KEEP qualifier to retain any intermediate - 
table of contents files. 


If you do not specify /CONTENTS on the DOCUMENT command line when 
you process a file that contains a <CONTENTS_FILE> tag, VAX DOCUMENT 
issues warning messages and the most recent version of the table of contents 
file is included. Note that this may result in an out-dated table of contents 
being included in your document. If there is no previous table of contents file 
to be included, the device converter issues an error message. 


Device Keyword 


Note: 


DOCUMENT 


The /CONTENTS qualifier is valid only if text formatting is being done. 
If /NOTEXT_FORMATTER is specified with the /CONTENTS qualifier, 
the /CONTENTS qualifier is ignored, and VAX DOCUMENT issues an 
informational message stating that you have specified conflicting qualifiers. 


Note that if you process your document with the /NOTAG—_TRANSLATOR 
and /CONTENTS qualifiers, and the table of contents is included using 
the <CONTENTS_FILE> tag, the table of contents is both incorporated into 
your document and placed in the file filename_CONTENTS and processed 
separately. 


The maximum length of a VMS file name is 39 characters. If you want to 
generate a contents file, your input file name must have no more than 30 
characters, because appending _CONTENTS to it adds 9 more characters. 


/DEVICE_CONVERTER|=(device-keyword [,device- 
keyword... ])] 
/NODEVICE_CONVERTER 


Specifies whether the device converter should be run. 


The device converter reads and processes an intermediate device-specific 
file and converts it to a file suitable for output on the destination device. 
The output from the device converter has the same file name as the input 
file specified on the command line, and a file type based on the destination 
keyword specified on the command line. 


The /DEVICE_CONVERTER qualifier optionally accepts the following 
keywords for special processing of your file: 


Description 


HORIZONTAL _OFFSET=number-of-points | Specifies where the text is to be positioned, relative to the left 


edge of the paper. The default horizontal offset for the page is 
one inch (72 points). 


The number-of-points argument specifies the number of points 
the text page should be moved to the right from the left edge 
of the paper. This argument must be zero or a positive integer. 
The left edge of the paper is assumed to be zero. 


VERTICAL _OFFSET=number-of-points Specifies where the text is to be positioned, relative to the top 


edge of the paper. The default vertical offset for the page is 
one inch (72 points). 


The number-of-points argument specifies the number of points 
the text page should be moved toward the page bottom from 
the top edge of the page. This argument must be zero or a 
positive integer. The top edge of the paper is assumed to be 
zero. 


STARTING__PAGE=folio-spec Specifies the beginning page number of the first page in a range 


of pages to be printed. If no ending page is specified, the rest 
of the file is printed. The folio-spec value can be any valid page 
number that VAX DOCUMENT produces on the page’. 


'See the definition of a folio-spec in the description of the /DEVICE_CONVERTER qualifier. 


DOCUMENT 


Device Keyword 


ENDING_PAGE=folio-spec 


NUMBER_OF_PAGES=maximum-pages 


FALLBACK 


Description 


Specifies the ending page number of the last page in a range of 
pages to be printed. The folio-spec value can be any valid page 
number that VAX DOCUMENT produces on the page’. If both 
the ENDING_PAGE and NUMBER_OF_PAGES keywords are 
used together on the same command line, VAX DOCUMENT 
issues an error message. 


Specifies the number of pages to print, when no ENDING 
PAGE keyword is specified. If both the ENDING_PAGE and 
NUMBER_OF_PAGES keywords are used together on the same 
command line, VAX DOCUMENT issues an error message. 


The maximum-pages value must be an integer specifying the 
total number of pages to print. If this number is specified as a 
number larger than the number of pages in the document (for 
example, 99999), all pages of the document are printed. 


Specifies that the device converter should not process the input 
file using the multinational character set. Use this keyword 
only when you do not want to use the multinational character 
set when processing a file for a device that does not support 
the multinational character set; for example, certain 7-bit line 
printers and terminals. 


'See the definition of a folio-spec in the description of the /DEVICE_CONVERTER qualifier. 


Use the STARTING_PAGE and ENDING_PAGE keywords to specify the 
page numbers that are to be processed. Each of these keywords accepts a 
folio-spec argument. A folio-spec has the following syntax: 


[{folio-prefix}{separator}] {page-number} 


The following list describes the rules for each of the folio-spec syntax 


elements. 


© page-number 


\ 


Specifies the page number portion of a folio-spec. In the folio-spec 11-3, 
“3” is the page-number. The page-number can be a Roman number, an 
Arabic number, or an asterisk (*). Roman numbers specify a page in the 
preface of a document, Arabic numbers specify pages outside the preface 
section, and the asterisk (*) specifies the first page of the document 
section specified by the folio-prefix. 


e = folio-prefix 


Specifies the numbers or letters that prefix the folio-spec. A folio-prefix 
can be any of the following: 


— Any single letter. Specifies an appendix in your document, for 
example the letter “B” in the folio-spec B-6. 


— Any single number. Specifies a chapter number, for example the 
number “13” in the folio-spec 13-1. 


— The keywords GLOSSARY or INDEX. Specifies a page in the glossary 
or index, for example “INDEX” in the folio-spec INDEX-6. 


— The keyword PARTn where n is an integer of one or greater. Specifies 
a section begun using a <PART_PAGE> tag, for example “PART2” in 
the folio-spec PART2-7. 


DOCUMENT 


— An asterisk (*). Specifies the first section of your document. 
¢ separator 


Specifies the character that separates the folio-prefix from the page- 
number. The separator can be any single character that is not a space, 
a number, or a letter. In the folio-spec 11-3, “—” is the folio-prefix. A 
separator must be omitted if no folio-prefix is specified. 


The following DOCUMENT command specifies that pages 11-3 through 11-8 
of file MYREPORT.DVI_LNO3 should be processed by the device convertor. 


$ DOCUMENT/NOTAG/NOTEXT myreport REPORT LNO3 - 
_$ /DEVICE=(STARTING=11-3, ENDING=11-8) 


/DIAGNOSTICS/[=file-spec] 
/NODIAGNOSTICS 


Causes the tag translator to write VAX Language-Sensitive Editor (LSE) 
diagnostics records to a file. LSE uses these records during its REVIEW 
phase to locate and describe translation errors. See Appendix B for more 
information on LSE. 


If you omit the file specification, the output file has the same name 
as the input file, with a file type of DIA. The default qualifier is 
/NODIAGNOSTICS. 


The /DIAGNOSTICS qualifier is valid only if tag translation is being done. 
If /NOTAG_TRANSLATOR is specified with the /DIAGNOSTICS qualifier, 
the /DIAGNOSTICS qualifier is ignored, and VAX DOCUMENT issues an 
informational message stating that you have specified conflicting qualifiers. 


/ELEMENT=file-spec 

Names the file specification of the book element that includes the input file 
specified on the DOCUMENT command line. If you use the /ELEMENT 
qualifier, the /PROFILE qualifier must also be used to specify the profile for 
the book that contains the book element. If you do not specify the file type 
of the element file, the default element file type is SDML. 


The /ELEMENT qualifier is valid only if tag translation is being done. 

If /NOTAG_TRANSLATOR is specified with the /ELEMENT qualifier, 
the /ELEMENT qualifier is ignored, and VAX DOCUMENT issues an 
informational message stating that you have specified conflicting qualifiers. 


/INCLUDE=file-spec 

Specifies a VAX DOCUMENT file that you want to be included before the 
input file you specified on the command line. If you do not specify the file 
type of the file to be included, SDML is the default file type. 


The /INCLUDE qualifier is valid only if tag translation is being done. 

If /NOTAG_TRANSLATOR is specified with the /INCLUDE qualifier, 
the /INCLUDE qualifier is ignored, and VAX DOCUMENT issues an 
informational message stating that you have specified conflicting qualifiers. 


/JINDEX[=(index-keyword [,index-keyword...])] 


/NOINDEX | 
Specifies whether an index file should be produced. The /NOINDEX qualifier 
is the default and specifies that no index should be produced. When the 
/INDEX qualifier is specified, VAX DOCUMENT creates an index file with a 
file name of input-filename_INDEX. 
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If you place the <INDEX_FILE> tag in your SDML file and also specify 
/DEVICE_CONVERTER on the command line, the current index file 

is included at the corresponding point in the final printable output file 
(filename.LNO3, filename.PS, and so on). If you do not place the <INDEX_— 
FILE> tag in your SDML file, the index is not incorporated into your final 
output file, but is placed in the separate file input-filename_INDEX. 


The file type of this index output file depends upon the destination keyword 
and the processing qualifiers you have selected on the DOCUMENT 
command line. You can use the /KEEP qualifier to retain any intermediate 
index files. 


If you do not specify /INDEX on the DOCUMENT command line when you 
process a file that contains an <INDEX_FILE> tag, VAX DOCUMENT issues 
a warning message and the most recent version of the index file is included. 
This may result in an out-dated index being included in your document. If no 


previous index file exists, the device converter issues an error message. 


Note: 


The /INDEX qualifier is valid only if text formatting is being done. If 
/NOTEXT_FORMATTER is specified with the /INDEX qualifier, the /INDEX 
qualifier is ignored, and VAX DOCUMENT issues an informational message 
stating that you have specified conflicting qualifiers. 


Note that if you process your document with the /NOTAG_TRANSLATOR 
and /INDEX qualifiers, and the index is included using the <INDEX_FILE> 
tag, the index is both incorporated into your document and placed in the file 
filename_INDEX and processed separately. 


The maximum length of a VMS file name is 39 characters. If you want to 
generate an index file, your input file name must have no more than 33 
characters, because appending _INDEX to it adds 6 more characters. 


The following list describes the optional indexing keywords that can be used 
with the /INDEX qualifier. 


DOCUMENT 


Index Keyword Description 
{ GUIDE_HEADINGS \ Specifies whether alphabetic headings are created for each 
NOGUIDE_HEADINGS letter group in the index. (The entries beginning with “A” will 


have an A at the start of the group, and so on.) The GUIDE_ 
HEADINGS keyword is the default. The NOGUIDE_HEADINGS 
keyword suppresses guide headings in the index output file. 
NONALPHA=AFTER 
SORT=([ { oro: \ [, NONALPHA=BEFORE ) 
NONALPHA=IGNORE 


Specifies the sorting algorithm used to order entries in an 
index. 


e SORT=LETTER sorts the entries letter by letter and 
ignores spaces and hyphens. SORT=LETTER is the 
default. 


e SORT=WORD sorts the entries letter by letter and treats 
spaces and hyphens as significant. 


e ~SORT=NONALPHA positions entries with initial 
nonalphanumeric characters in the index based on the 
keyword supplied with the NONALPHA keyword. 


— The AFTER keyword causes entries with initial 
nonalphanumeric characters to be placed at the end 
of the index. 


— The BEFORE keyword causes entries with initial 
nonalphanumeric characters to be placed at the 
beginning of the index. 


— The IGNORE keyword causes entries with initial 
nonalphanumeric characters to be sorted by the first 
alphanumeric characters in the entry. The default is 
NONALPHA=IGNORE. 


{ OVERRIDE_MASTER \ Specifies the disposition of index entries in both single- 

NOOVERRIDE_MASTER document indexes and master indexes; NOOVERRIDE— 
MASTER is the default keyword for both /INDEX and 
/MASTER_INDEX. 


Use /INDEX=NOOVERRIDE_MASTER to create a single 
document index that contains only the index entries that 
are not marked with the MASTER keyword; this is the 
default. 

Use /INDEX=OVERRIDE_MASTER to create a single 
document index that contains both the index entries 

that are not marked with the MASTER keyword and the 
entries that are marked with the MASTER keyword. 

Use /MASTER_INDEX=NOOVERRIDE_MASTER to create 
a master index that contains only the index entries that 
are marked with the MASTER keyword; this is the default. 
Use /MASTER_INDEX=OVERRIDE_MASTER to create a 
master index that contains both the index entries that are 
not marked with the MASTER keyword and those entries 
that are marked with the MASTER keyword. 
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/KEEP|[=(filetype-keyword [,filetype-keyword...] )] 
/NOKEEP | | 


Specifies whether intermediate files should be kept or deleted. The default 
qualifier /NOKEEP indicates that the intermediate files should be deleted by 
VAX DOCUMENT after processing. 


The following keywords can be used to specify individual intermediate files 
that are to be kept: 





File Type 
Keyword File Contents 
DVI Specifies an intermediate output file from the text formatter. You 


may want to keep this file for reprocessing at a later date, or to 
selectively process and print only certain pages. 


The actual file type of this file is based on the destination keyword 
you specified on the DOCUMENT command line. These file types 
and the destination keywords that create them are listed under the 
description of the /TEXT_FORMATTER qualifier. 


INX Specifies an ASCII file that contains index entries in page-number 
order. This file can be used to create master indexes. 


TEX Specifies an input file for the text formatter. Note that a TEX file 
processed under a certain doctype design can produce errors if it 
is reprocessed using a different doctype. 


/LIST[=file-spec] 

/NOLIST 

Specifies whether a listing file is produced. The /NOLIST qualifier is the 
default and suppresses the generation of a listing file. If no file specification is 
provided as an argument to the /LIST qualifier, the qualifier causes a listing 
file to be produced with the file name of the input file specification and a 
default file type of LIS. If a file specification is provided as an argument, then 
that file specification is used as the output file. 


The listing file contains the following information: 
e All messages generated by the tag translator 

e All messages generated by the text processor 

e All messages generated by the device converter 


e A brief summary section. This summary includes the following 
information: 


— The original command line 
— The time and day that processing began 
— The total CPU time used 


/LOG 
/NOLOG 


Specifies whether informational messages should be issued during processing. 
The /LOG qualifier is the default and specifies that informational messages 
should be issued. The /NOLOG qualifier suppresses informational messages. 
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The following example shows the typical informational messages displayed 
during tag translation (not specifying /NOLOG is the same as specifying the 
default qualifier /LOG): 


$ DOCUMENT myarticle ARTICLE LNO3 
%DOC-I-IDENT, VAX DOCUMENT V1.1 


{Tag Translation]... 
“%TAG-I-DEFSLOADD, End of Loading of Tag Definitions 
“%TAG-I-ENDPASS_1, End of first pass over the input 
ET ext Ff oO rmat toi n-€ ees 


The following example shows how no messages are displayed when 
/NOLOG is specified. Note that only the DCL dollar ($) prompt is returned 
after the DOCUMENT command is finished. 


$ DOCUMENT myarticle ARTICLE LNO3 /NOLOG 
$ 


/MAPI=file-spec] 


/NOMAP 

Specifies whether all the input files processed by VAX DOCUMENT should 
be listed in a file, which starts with the SDML input file and includes the tag 
table and any SDML files specified by the /INCLUDE or /SYMBOLS qualifier 
or the <ELEMENT> or <INCLUDE> tags. Files that are included by other files 
are indented under those files in this listing. The default file type of the file 
to be created is MAP_LIS. The default qualifier is /NOMAP. 


The /MAP qualifier is valid only if tag translation is being done. If 
/NOTAG_TRANSLATOR is specified with the /MAP qualifier, the /MAP 
qualifier is ignored, and VAX DOCUMENT issues an informational message 
stating that you have specified conflicting qualifiers. 


/MASTER_INDEX[=(index-keyword [,index- 
keyword...])] 
/NOMASTER_INDEX 


Causes indexing files to be collated into a master index file. 


When the /MASTER_INDEX qualifier is specified, VAX DOCUMENT expects 
a master index data file as the input-file-spec parameter. This file lists the 
index output (INX) files generated from the individual books that are being 
referenced in the master index. The default file type of this input file is 
INX_LIST. 


This qualifier accepts the same optional indexing keywords as the /INDEX 
qualifier; see the description of the /INDEX qualifier for a list of these 
keywords and their uses. See Chapter 7 for more information on creating a 
master index. 


/OUTPUT=file-spec 

Specifies a new name for the output file. If the /OUTPUT qualifier is not 
used, the output file is given the same file name as the input file, but with a 
file type based on the other qualifiers and destinations chosen. 


The output file type is determined by the output device specified by the 
destination keyword. An example of a command line that uses the /OUTPUT 
qualifier follows: 


$ DOC somefile LETTER LNO3 /NOTEXT_FORMATTER /OUTPUT=anotherfile 
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This command line would create the file ANOTHERFILE.TEX because 

the processing was completed before the text formatter was run by the 
/NOTEXT_FORMATTER qualifier. If /NOTEXT_FORMATTER had been 
omitted from the preceding command line, the output file would have been 
ANOTHERFILE.LNO3 


The following table lists the output file types and the default destination 
keywords that produce them. 


Default Destination Keyword Default File Type 


LINE LINE 
LNOS3 LNO3 
PS PS 
TERMINAL TERM 
MAIL TXT 


/PRINT[=(qualifier-keyword [, qualifier-keyword...])] 
/NOPRINT 


Specifies whether the output file should be printed. The /PRINT qualifier 
builds and issues a DCL PRINT command. You can use any of the DCL 
PRINT command qualifiers with VAX DOCUMENT by passing these 
qualifiers as keywords to the /PRINT qualifier. 


For example, if you want to print two copies of a VAX DOCUMENT file with 
no flag page, you can use the PRINT command as follows: 


$ PRINT somefile.line /NOFLAG/COPIES=2 


You can specify the same options using the following /PRINT qualifier on the 
DOCUMENT command line. 


$ DOC/NOTAG/NOTEXT/NODEV somefile - 
_$/PRINT=(NOFLAG ,COPIES=2) LETTER LINE 


When you use the /PRINT qualifier, you do not need to specify an output 
device; VAX DOCUMENT determines the appropriate output device from the 
destination keyword specified on the DOCUMENT command line. 


Default print queues for each of the destination keywords available at your 
site are established when VAX DOCUMENT is installed. These queues 
include all DCL PRINT command qualifiers needed for correct printing on 
that output device. 


If you choose to specify a print queue other than the default, you must 
also specify the correct qualifier-keywords needed for that queue. These 
keywords vary depending on the type of file to be printed (indicated by the 
file extension) and the type of output device. 


Output 
File Type 


LINE 


LNOS3 


PS 


Output 
File Type 


LINE 


LNO3 


PS 


Print 
Device 


Line Printer 
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The following table shows the keywords to use for each file and output device 
combination. 


DOCUMENT /PRINT Qualifier-Keywords 
/PRINT=(QUEUE=queuename) 


LNOS3 Laser Printer 
LNO3 PLUS Laser Printer 


LNO3R SCRIPTPRINTER /PRINT=(QUEUE=queuename,PARAM=DATA_T YPE=ANSI) 
PRINTSERVER 40 


LNO3 Laser Printer /PRINT=(QUEUE=queuename,NOFEED,PASSALL) 
LNOS3 PLUS Laser Printer 
LNO3R SCRIPTPRINTER /PRINT=(QUEUE=queuename,PARAM=DAT A_TYPE=ANSI) 


PRINTSERVER 40 


LNO3R SCRIPTPRINTER /PRINT=(QUEUE=queuename,PARAM=DAT A_TYPE=POST) 
PRINTSERVER 40 


If you wish to print your file using the DCL PRINT command, the following 
table shows the qualifiers you must use for each supported device. 


Print 

Device DCL PRINT Command Qualifiers 

Line Printer $ PRINT filename.LINE 

LNO3 Laser Printer _$ /QUEUE=queuename 

LNO3 PLUS Laser Printer 

LNO3R SCRIPTPRINTER $ PRINT/PARAM=(DATA_TYPE=ANSI) filename.LINE 
PRINTSERVER 40 _$ /QUEUE=queuename 

LNOS Laser Printer $ PRINT/NOFEED/PASSALL filename.LNO3 

LNO3 PLUS Laser Printer —$ /QUEUE=queuename 

LNO3R SCRIPTPRINTER $ PRINT/PARAM=(DATA_TYPE=ANSI) filename.LNO3 
PRINTSERVER 40 _$ /QUEUE=queuename 

LNO3R SCRIPTPRINTER $ PRINT/PARAM=(DATA_TYPE=POST) filename.PS 
PRINTSERVER 40 _$ /QUEUE=queuename 


When you specify /DEVICE_CONVERTER on the DOCUMENT command 
line, /PRINT is the default printing qualifier when the destination keywords 
are LNO3, PS, or LINE. The /NOPRINT qualifier is the default when the 
destination keywords are TERMINAL or MAIL. 


Note that if any serious errors are encountered during processing, the file is 
not sent to the print device. 


/PROFILE=file-spec 

Specifies that the input file is a file referenced by the <ELEMENT> tag in 

a bookbuild profile and that a cross-reference data file created by a VAX 
DOCUMENT bookbuild should be used to resolve any cross references in 
the input file. The cross-reference data file is specified as an argument to the 
/PROFILE qualifier and has a file type of XREF. 
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The /PROFILE qualifier is valid only if tag translation is being done. If 
/NOTAG_TRANSLATOR is specified with the /PROFILE qualifier, the 
/PROFILE qualifier is ignored, and VAX DOCUMENT issues an informational 
message stating that you have specified conflicting qualifiers. 


/SYMBOLS=file-spec 

/NOSYMBOLS 

Controls whether a file of symbol definitions is to be read automatically 
during tag translation. The default qualifier is /NOSYMBOLS. The SDML 
input file accessed through the /SYMBOLS qualifier should contain only 
symbol definitions created by the <DEFINE-SYMBOL> and the <DEFINE— 
BOOK_NAME> tags. The default file type of this file is SDML. 


The /SYMBOLS qualifier is valid only if tag translation is being done. 

If /NOTAG_TRANSLATOR is specified with the /SYMBOLS qualifier, 
the /SYMBOLS qualifier is ignored, and VAX DOCUMENT issues an 
informational message stating that you have specified conflicting qualifiers. 


/TAG_ TRANSLATOR 
/NOTAG_TRANSLATOR 


Controls whether the tag translator is run. If this qualifier is not specified, the 
default qualifier is /TAG_TRANSLATOR. 


If the input-file-spec parameter specified on the command line does not 
include a file type, the default file type is SDML. By default, the tag translator 
produces an output file with the file name of the input file and a file type of 
TEX. This file can then be used as an input file to the text formatter. 


/TEXT_FORMATTER 
/NOTEXT_FORMATTER 


Controls whether the text formatting program is run. If /NOTEXT_ 
FORMATTER is specified, VAX DOCUMENT processing stops after the 
tag translator completes. /TEXT_FORMATTER is the default. 


If /NOTAG_TRANSLATOR is specified and the input file specified on the 
command line does not include a file type, the default file type is TEX. The 
output file from the text formatter can have one of several file types based on 
the destination parameter entered on the command line. These default output 
file types and their related destination keywords are given in the following 
list. 


Destination Intermediate Final 

Keyword Output File Type Output File Type 
LINE DVI_LINE LINE 

LNO3 DVI_LNO3 LNO3 

MAIL DVI_LINE TXT 

PS DVI_PS PS 

TERMINAL DVI_LINE TERM 


The output file from the text formatter can then be used as an input file to the 
device converter. 





VAX DOCUMENT Command Summary 





EXAMPLE When you process your input file using the DOCUMENT command, you are 
actually running your file through several processors. The following example 
shows a typical use of the VAX DOCUMENT command: 


$ DOCUMENT myreport.SDML REPORT LNO3 /CONTENTS 


%DOC-I-IDENT, VAX DOCUMENT V1.1 


{Tag Translation]... 
“%TAG-I-DEFSLOADD, End of Loading of Tag Definitions 
%TAG-I-ENDPASS_1, End of first pass over the input 
[Text Formatting]... 
4TEX-I-PAGESOUT, 17 pages written. 
-TEX-I-OQUTFILENAME, 'DUA1: [DOCFILES]MYREPORT.DVI_LNO3' 
[Contents Generation]... 
[Text Formatting Contents]... 
%4TEX-I-PAGESOUT, 1 page written. 
-TEX-I-OQUTFILENAME, 'DUA1: [DOCFILES]MYREPORT_CONTENTS.DVI_LNO3' 
[Device Conversion]... 
%DVC-I-PAGESOUT, 18 pages written to file: 

DUA1: [DOCFILES] MYREPORT .LNO3 
[Contents Device Conversion]... 
%DVC-I-PAGESOUT, 1 page written to file: 


DUA1 : [DOCFILES] MYREPORT_CONTENTS.. LNO3 
CP ea a ting. oF 2 De]... 
Job MYREPORT (queue SYS$LNO3, entry 833) started on SYS$LNO3 


[Printing Contents]... 
Job MYREPORT_CONTENTS (queue SYS$LNO3, entry 834) started on SYS$LNO3 
$ 
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B sUsing LSE with VAX DOCUMENT 


This appendix provides an overview of an optional productivity tool, the 
VAX Language-Sensitive Editor. This tool is not included with the VAX 
DOCUMENT software; it must be purchased separately. Using LSE can 
increase your productivity as a VAX DOCUMENT user. For information on 
how to purchase this tool, contact your DIGITAL sales representative. 





B.1 Using LSE with VAX DOCUMENT 


The VAX Language-Sensitive Editor (LSE) is a powerful and flexible text 
editor designed specifically for software development. LSE has important 
features that help you produce syntactically correct SDML markup in VAX 
DOCUMENT. 


To invoke LSE, issue the LSEDIT command followed by a file name with a 
SDML file type at the DCL prompt. For example: 


$ LSEDIT USER .SDML 


The following sections describe some of the key features of LSE. Section B.1.1 
discusses how to enter source code using LSE and Section B.1.2 describes 
LSE’s compiler interface features. Section B.1.3 gives examples of how to 
generate VAX DOCUMENT source code with LSE. 


For more details on advanced features of LSE, see the Guide to VAX Language- 
Sensitive Editor and VAX Source Code Analyzer. 


B.1.1 Entering Source Code Using Tokens and Placeholders 


LSE simplifies the tasks of developing and maintaining documents. LSE 
provides the functions of a traditional text editor, plus additional powerful 
features: language-specific placeholders and tokens, aliases, compile and 
review features. 


Placeholders are markers in the source code that indicate locations where you 
can provide text. Placeholders help you to supply the appropriate syntax in a 
given context. Generally, you do not need to type placeholders; rather, they 

are inserted for you by LSE. 


Placeholders are either optional or required. Required placeholders, which are 

_ delimited by braces ({}), represent places in the source code where you must 
provide text. Optional placeholders, which are delimited by brackets ([]), 
represent places in the source code where you can either provide additional 
constructs or delete the placeholder. 


There are three types of LSE placeholders. 


Using LSE with VAX DOCUMENT 


B-2 


Type of 

Placeholder Description 

Terminal Provides text that describes valid replacements for the 
placeholder 

Nonterminal Expands into additional language constructs 

Menu Provides a list of options corresponding to the placeholder 


You can move forward or backward from placeholder to placeholder. In 
addition, you can delete or expand placeholders as needed. Section B.1.3 
shows examples of expanding placeholders. 


Tokens typically represent each tag in VAX DOCUMENT. When expanded, 
tokens provide the complete syntax of a tag. You can type tokens directly 
into the buffer. Generally, you use tokens when you want to add a tag and 
there are no placeholders in an existing program. For example, typing COM 
and issuing the EXPAND command causes the tags for a comment to appear 
on your screen. You can also use tokens to by-pass long menus in cases 
where expanding a placeholder, such as [element-or-template], would result 
in a lengthy menu. 


You can use tokens to insert text when editing an existing file by typing the 
name for a function or keyword and issuing the EXPAND command. 


LSE commands allow you to manipulate tokens and placeholders. These 
commands and their default key bindings are as follows: 


Table B—1 LSEDIT Commands 


Key 

Command Binding Function 

EXPAND CTRL/E Expands a placeholder 

UNEXPAND PF1-CTRL/E Reverses the effect of the 
most recent placeholder 
expansion 

GOTO PLACEHOLDER/FORWARD CTRL/N Moves the cursor to the 
next placeholder 

GOTO PLACEHOLDER/REVERSE CTRL/P Moves the cursor to the 
previous placeholder 

ERASE PLACEHOLDER/FORWARD ~~ CTRL/K Erases a placeholder 

UNERASE PLACEHOLDER PF1-CTRL/K Restores the most recently 
erased placeholder 

None Down arrow Moves the indicator down 
through a menu 

None Up arrow Moves the indicator up 
through a menu 

None { ENTER \ Selects a menu option 

RETURN 


You can display a list of all defined tokens and placeholders, or a particular 
token or placeholder, with the LSE commands=—_—_. SHOW TOKEN and SHOW 
PLACEHOLDER. 
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To copy the listed information into a separate file, first issue the appropriate 
SHOW command to put the list into the $SHOW buffer. Then issue the 
following commands: 


LSE> GOTO BUFFER $SHOW 
LSE> WRITE filename 


To obtain a hard copy of the list, use the PRINT command at DCL level to 
print the file you created. 


B.1.2 Compiling Source Code 


To compile your code and review compilation errors without leaving the 
editing session, you can use the LSE commands COMPILE and REVIEW. 
The COMPILE command issues a DCL command in a subprocess to invoke 
the VAX DOCUMENT tag translator. The compiler then generates a file of 
compile-time diagnostic information that LSE can use to review compilation 
errors. The diagnostic information is generated with the /DIAGNOSTICS 
qualifier that LSE appends to the compilation command. 


For example, to issue the COMPILE command while in the buffer 
USER.SDML, you would use the following command: 


COMPILE $ doctype destination 


The doctype and destination are any valid VAX DOCUMENT keywords. When 
the COMPILE command is issued, the following DCL command executes: 


$ DOCUMENT USER.SDML/DIAGNOSTICS=USER.DIA doctype destination 
LSE supports all of VAX DOCUMENT’s command qualifiers. 


The REVIEW command displays any diagnostic messages that result from 

a compilation. LSE displays the compilation errors in one window and the 
corresponding source code in a second window so that you can review your 
errors while examining the associated source code. This capability eliminates 
tedious steps in the error correction process and helps ensure that all the 
errors are fixed before you recompile your program. 


LSE provides several commands to help you review errors and examine 
your source code. These commands, and their default key bindings where 
applicable, are as follows: 


Command Key Binding Function 
COMPILE None Compiles the contents of the source buffer. 


You can issue this command with the 
/REVIEW qualifier to put LSE in REVIEW 
mode immediately after the compilation. 


REVIEW None Puts LSE into REVIEW mode and displays 
any errors resulting from the last compilation. 
END REVIEW None Removes the buffer $REVIEW from the 


screen; returns the cursor to a single window 
containing the source buffer. 


GOTO SOURCE CTRL/G Moves the cursor to the source buffer that 
contains the error. 
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Command Key Binding Function 
NEXT STEP CTRL/F Moves the cursor to the next error in the 
buffer $REVIEW. 
PREVIOUS CTRL/B Moves the cursor to the previous error in the 
STEP buffer $REVIEW. 
{ Down arrow \Moves the cursor within a buffer. 
Up arrow 


The following sections show examples of using some common tokens and 
placeholders to write VAX DOCUMENT code. The examples are expanded 
to show the formats and guidelines LSE provides; however, not all of the 
examples are fully expanded. 


The examples show expansions of the following VAX DOCUMENT features: 
e Tags as tokens: <LIST> and <TABLE> 
e Initial string: [element-or-template] 


e Sample template: Data Item Description (DID) for U.S. Department of 
Defense military specification 


Instructions and explanations precede each example, and an arrow (+) 
indicates the line in the code where an action has occurred. 


See Table B-1 for the commands that manipulate tokens and placeholders. 


Remember that braces ({}) enclose required placeholders; brackets ([]) 
enclose optional placeholders. Note that when you erase an optional 

placeholder, LSE also deletes any associated text before and after that 
placeholder. 


When the editor is used to create a new VAX DOCUMENT file, the initial 
string, {element-or-template}, will appear at the top of the screen. Expansion 
of the initial string will produce the following 


-> [profile] 
[front_matter] 
[chapter] 

[part] 

[appendix] 

[glossary] 

[tag-groups] 

[article-tags] 

[letter-tags] 

[report-tags] 

[overheads-tags] 
{milspec-templates] 
[software-documentation-templates] 


A convention in VAX DOCUMENT is to place a single element, such as a 
chapter or appendix, or a single template, such as a milspec template or a 
software documentation template, into a single file. 


B.1.3.1 


B.1.3.2 
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Lists 
Select the token LIST by typing LIS and expanding the token. 


From the menu of possible list types, select the option Alphabetical-list. The 
following then appears on the screen in the editing buffer: 


<LIST> (ALPHABETIC\ [start -no] \ [case] ) 
{list-element}... 
<ENDLIST> 


Erase the placeholder [start-number] and expand the placeholder [case]. Select 
UPPERCASE. 


<LIST> (ALPHABETIC\UPPERCASE) 
{list-element}... 
<ENDLIST> 


Move to the next placeholder and expand to get an individual list element 
tag. 


<LIST> (ALPHABETIC\UPPERCASE) 
<LE>{text} 

[list-element]... 

<ENDLIST> 


Type over the {text} placeholder to insert the text for the first list item. 


Tables 
Enter all or part of the token TABLE and expand. 


<TABLE> ({caption}\ {symbol]) 
[<TABLE_ATTRIBUTES>] 
<TABLE_SETUP>({number}[\col-width] .. .) 
<TABLE_HEADS> ({heading} [\heading] .. .) 
{rows}... 

<ENDTABLE> 


The <TABLE> tag takes two arguments: the caption to the table and a 
symbol to use for cross-references. With the cursor positioned on {caption}, 
enter caption text. With the cursor positioned on [symbol], enter symbol text. 


-> <TABLE>(Caption for the Table\newsymbol_tab) 
[<TABLE_ATTRIBUTES>] 
<TABLE_SETUP> ({number}[\col-width] ...) 
<TABLE_HEADS> ({heading} [\heading] .. .) 
{rows}... 
<ENDTABLE> 


Next, expand the placeholder <TABLE_ATTRIBUTES> and choose a set of 
attributes from the menu. 


<TABLE>(Caption for the Table\newsymbol_tab) 
-> <TABLE_ATTRIBUTES> (WIDE\MULTIPAGE) 

<TABLE_SETUP> ({number}[\col-width] ...) 

<TABLE_HEADS> ({heading} [\heading] ...) 

{rows}... 

<ENDTABLE> 
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Next, set up the table for the number and width of columns desired. Enter 
a number indicating the number of columns (2 through 9). Then expand the 
{\col-width] placeholder to enter a number indicating the width of the first 
table column. 


<TABLE>(Caption for the Table\newsymbol_tab) 
<TABLE_ATTRIBUTES> (WIDE\MULTIPAGE) 

-> <TABLE_SETUP>(3\{number}[\col-width]...) 
<TABLE_HEADS> ({heading} [\heading] ...) 
{rows}... 
<ENDTABLE> 


Notice that the expansion of [\col-width] gives you the backslash needed to 
separate arguments and the {number} placeholder. If you enter a number 
into {\col-width] without expanding it first, you would not get the backslash. 
Enter column widths for each column in the table except the last column. 
Delete the last [\col-width] placeholder. 


<TABLE>(Caption for the Table\newsymbol_tab) 
<TABLE_ATTRIBUTES> (WIDE\MULTIPAGE) 

-> <TABLE_SETUP>(3\15\15 ) 
<TABLE_HEADS> ({heading} [\heading] .. .) 
{rows}... 


The {heading} placeholders work very similarly to the [\col-width] 
placeholder: 


<TABLE>(Caption for the Table\newsymbol_tab) 
<TABLE_ATTRIBUTES> (WIDE\MULTIPAGE) 
<TABLE_SETUP>(3\15\15 ) 
-> <TABLE_HEADS>(First heading\Second Heading\{heading}[\heading]...) 
{rows}... 
<ENDTABLE> 


Enter a heading for each column and delete the last [\heading] placeholder. 
Expand the {rows} placeholder to get tags for the body of the table. 


<TABLE>(Caption for the Table\newsymbol_tab) 

<TABLE_ATTRIBUTES> (WIDE\MULTIPAGE) 

<TABLE_SETUP>(3\15\15 ) 

<TABLE_HEADS> (First heading\Second Heading\{heading}[\heading] ...) 
-> <TABLE_ROW>({item}[\item]...) 

[rows]... 


Enter an item for each column and keep expanding the [rows] placeholder 
until the table body is complete. Delete the last [rows] placeholder and the 
table is ready for processing. 


Profile 


To place the tags for a document’s profile into the editing buffer, type PRO 
and expand the token. 


<PROF ILE> 
{element}... 
<ENDPROFILE> 
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Expand the placeholder {element} to get the <ELEMENT> tag and the 
optional <INCLUDES_FILE> tag. 


<PROF ILE> 
-> <ELEMENT> ({element-name}) 
[<INCLUDES_FILE>] 
{element]... 


<ENDPROF ILE> 


Expand or delete the placeholder <INCLUDES_FILE> and expand the 
placeholder [element] as many times as needed. 


Sample Template 
There are two methods of accessing the Data Item Description (DIDs) 
templates for DOD-STD-2167-related military specifications: 


¢ Select [milspec-templates] from the initial placeholder 


e Enter part of the token “DID-800...” and expand to get a list of the 
available data item descriptions 


Select one of the DIDs from the list. 


~> DI-MCCR-80012: Software Top Level Design Document 
DI-MCCR-80025: Software Requirements Specification 
DI-MCCR-80026: Interface Requirements Specification 
DI-MCCR-80027: Interface Design Document 
DI-MCCR-80028: Data Base Design Document 
DI-MCCR-80031: Software Detailed Design Document 


Select one of the DIDs, for example, DI-MCCR-80012. The menu that 
appears is a list of templates that make up the individual files in the Software 
Top Level Design Document. 


For example, select DI-MCCR-80012_ _cover_page: 


DI-MCCR-80012__profile 
DI-MCCR-80012__symbols 

-> DI-MCCR-80012__cover_page 
DI-MCCR-80012__Scope 
DI-MCCR-80012__Referenced_Documents 
DI-MCCR-80012__Requirements 
DI-MCCR-80012__Qualification_Requirements 
DI-MCCR-80012__Preparation_for_Delivery 
DI-MCCR-80012__Notes 
DI-MCCR-80012__Appendix 


Each of the menu items displayed for DI-MCCR-80012 contains a template 
for a section of the Software Top Level Design Document and should be 
placed in a separate file. 


<comment>(begin front matter component) 

<front_matter> 

<title_page> 
<specification_info>(<reference>(control_number) \\<DATE>\) 
<spec_title>(<reference>(DID80012_title)\For the\{text}\ 
Contract No. <reference>(contract_number) \ 

CDRL Sequence No. <reference>(CDRL_number) \<DATE>) 


<subtitle>(Prepared for:\{text}\ \ 
Prepared by: \{text}\{text}) 


Using LSE with VAX DOCUMENT 


<endtitle_page> 
<contents_file> 


<endfront_matter> 
<comment>(end front matter component) 


The tags in the cover page template mark standard title page text. Fill in the 
variable information by typing over the {text} placeholders. 


B.1.4 VAX DOCUMENT Tokens and Placeholders 


To see all of the defined tokens provided by VAX DOCUMENT, enter the 
following Editor command: 


LSE> SHOW TOKEN 


To see all of the defined placeholders provided by the VAX DOCUMENT, 
enter the following Editor command: 


LSE> SHOW PLACEHOLDER 


To print a copy of either of these lists, you must first enter the appropriate 
SHOW command. This enters the list into the $SHOW buffer. Then enter 
the following commands: 


LSE> GOTO BUFFER $SHOW 
LSE> WRITE filename 


At DCL level, you can use the PRINT command to obtain a hard copy of the 
list. 


You may also specify a token name or placeholder name after the SHOW 
TOKEN or SHOW PLACEHOLDER command to obtain information about a 
particular token or placeholder. 





C Messages 


A message has the following format: 
% facility--severity--identification, text 


Messages in VAX DOCUMENT can come from the following facilities: 


Facility code _—‘ Facility 
DOC The DOCUMENT command line 


TAG The tag translator 
TEX The text processor 
DVC The device converter 
INX The index facility 





The messages from these sources are given in the following sections. 


To locate a message, use the facility code to locate the appropriate section and 
then look for the identification text in that section. Messages are alphabetical 
within sections. 


For example, consider the following message: 


%TAG-W-ISTHISTAG, at text on line 245 in file 
WRT_: [YOURNAME . BOOK] INTRO. GNC; 
Ignoring <list. Is this a tag without a closing angle bracket? 


The facility code in this error is TAG, so you look in the section for tag 
translator message. The identification text is ISTHISTAG, so you locate that 
within the section. 


Messages 
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C.1 DOCUMENT Command Messages 
ACTION_EXCL , qualifier is not available for the chosen destination 


Warning: Indicates that the default qualifier has been excluded for the 
desired destination and will therefore be ignored. 


User Action: None. 


AMB_DESIGN , Ambiguous design keyword design-keyword 
Fatal: An ambiguous design keyword was specified. 


User Action: Change the specified design keyword to be a unique design 
keyword. 


AMB_DEST , Ambiguous destination keyword destination-keyword 
Fatal: An ambiguous destination keyword was specified. 


User Action: Change the specified destination keyword to be a unique 
keyword. 


AMB_PAPER_SIZE , Ambiguous paper size value 
Error: The specified paper size value is ambiguous. 


User Action: Specify a unique paper value and reexecute the DOCUMENT 
command. 


CANT_GET_VALUE , Cannot get value of /qualifier qualifier 
Fatal: A required value associated with the qualifier was not provided. 


User Action: Reexecute the DOCUMENT command and specify a value for 
the qualifier. 


CANT_OPEN , Error detected opening file file-spec 
Error: An error has occurred while opening the specified file. 


User Action: Fix problem if you can or else refer problem to your system 
manager. After fixing the problem, reexecute the DOCUMENT command. 


CANT_USE_SHR , Cannot use file-spec 
Fatal: A shareable image file for text processing could not be found or used. 


User Action: Consult system manager. 


DCL_ERROR, An error was detected while parsing 
\DCL-commanad\ 


Error: An error was detected by the DCL parser. 


User Action: Correct error on the specified line and reexecute the 
DOCUMENT command. . 
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DESIGN_ERROR , Bad design entry in design-file-directory DOC$DESIGNS data 
file 
Error: An error was found in a design data file, erroneous design entries are 
ignored. 


User Action: Correct error and reexecute the DOCUMENT command. 


DESIGN—SYNTAX , Ignoring design-keyword design entry 
Error: A syntax error is detected in the design data file. 


User Action: Correct error and reexecute the DOCUMENT command. 


DEST_ERROR , Bad destination entry in destination-file-directory 
DOC$DESTINATIONS data file 


Error: An error was found in a destination data file. Any involved entries 
ignored. 


User Action: Correct error and reexecute the DOCUMENT command. 


DEST_SYNTAX , Ignoring destination-keyword destination data entry 
Error: An error has been detected in a destination data file. 


User Action: Correct errors in the destination data file and reexecute the 
DOCUMENT command. 


DO_CONTENTS, [Contents Generation]... 
Informational: Indicates that a contents file is being created. 


User Action: None. 


DO_DEVICE, [Device Conversion]... 


Informational: Indicates that the document input is being processed into a 
printable form. 


User Action: None. 


DO_DVC_CONTENTS, [Contents Device Conversion]... 


Informational: Indicates that the document contents is being processed into 
a printable form. 


User Action: None. 


DO_DVC_INDEX, [Index Device Conversion]... 


Informational: Indicates that the document index is being processed into a 
printable form. 


User Action: None. 


DO_INDEX, [Index Generation]... 
Informational: Indicates that an index file is being created. 


User Action: None. 
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DO_MASTER_INDEX, [Master Index Generation]... 
Informational: Indicates that a master index file is being created. 


User Action: None. 


DO_PRINT, [Printing File]... 


Informational: Indicates that your output file is being sent to the designated 
print queue. ; 


User Action: None. 


DO_TAG, [Tag Translation]... 


Informational: Indicates that the tag translator is processing your SDML 
input file. 


User Action: None. 
DO_TEXT, [Text Formatting ]... 
Informational: Indicates that the text formatter is processing. 


User Action: None. 


DO_TEXT_CONTENTS, [Text Formatting Contents]... 
Informational: Indicates that the text formatter is processing the contents file. 


User Action: None. 


DO_TEXT_INDEX, [Text Formatting Index]... 
Informational: Indicates that the text formatter is processing the index file. 


User Action: None. 


ERROR—_CONVERTER , Errors found by the device converter 
Error: The device converter has ended in error, processing cannot continue. 


User Action: Correct errors found by the device converter and reexecute the 
DOCUMENT command. 


ERROR_FORMATTER , Errors found by the text formatter 
Error: The text formatter has ended in error, processing cannot continue. 


User Action: Correct errors found by the text formatter and reexecute the 
DOCUMENT command. 


ERROR_IN_DESIGN , Internal design date file error 
Fatal: An unspecified error in the design data file was found. 


User Action: Refer problem to system manager. If you receive this message 
and are under a service contract with DIGITAL, call your customer service 
center. Otherwise, submit a Software Performance Report. 
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ERROR_IN_DEST , Internal destination data file error 
Fatal: An unspecified error in the destination data file was found. 


User Action: Refer problem to system manager. If you receive this message 
and are under a service contract with DIGITAL, call your customer service 
center. Otherwise, submit a Software Performance Report. 


ERROR_TAG , Errors found by the tag translator 
Error: The tag translator has ended in error, processing cannot continue. 


User Action: Correct errors found by the tag translator and reexecute the 
DOCUMENT command. 


ERROR_WRITE , Error writing to file file-spec 


Fatal: An RMS error was reported when DOCUMENT tried to read the 
specified file. 


User Action: Correct RMS error and reexecute DOCUMENT command. 
ERR—CRE8_LIST , Listing file file-spec cannot be created 
Fatal: The specified listing file could not be created. 


User Action: Correct error in the listing file specification. 


FILLM_TOO_LOW , Process open file limit too low, required value is minimum- 
value 


Fatal: The FILLM of the current process in not large enough to run the 
DOCUMENT command. 


User Action: Contact system manager to increase quota. 


IDENT , VAX Document version number 
Informational: DOCUMENT version number identification message 


User Action: None. 


IGNOR_DESIGN , Ignoring optional logical-name design data file 


Informational: Optional DOC$LOCAL FORMATS or DOC$STANDARD_ 
FORMATS design file cannot be opened. Any designs which are in that file 
will be unavailable. 


User Action: Correct reported problem or contact system manager, then 
reexecute the DOCUMENT command. 
INVALID_DESIGN , design-keyword is not a valid design 


Fatal: An unrecognized design parameter was specified on the DOCUMENT 
command line. 


User Action: Reexecute the DOCUMENT command with a valid design 
parameter. 
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INVALID_DEST , destination-keyword is not a valid destination 


Fatal: An unrecognized destination keyword was specified on the 
DOCUMENT command line. 


User Action: Reexecute the DOCUMENT command with a valid destination 


keyword. 
INVALID_DVI_ARG , qualifier-arg is not a valid /DEVICE_CONVERTER 
argument 
Fatal: The argument value specified to /DEVICE_CONVERTER is 
unrecognized. 
User Action: Reexecute DOCUMENT command with a valid qualifier 
argument. 


INVALID_ENTRY , qualifier-entry is not a valid /qualifier entry 
Fatal: An invalid qualifier entry was specified on the DOCUMENT command. 


User Action: Reexecute the DOCUMENT command with a valid qualifier. 
Refer to Appendix A in this manual for information on valid DOCUMENT 
command qualifiers. 


INVALID_INPUT , Cannot use file-spec as an input file 
Fatal: The specified input file is invalid. 
User Action: Reexecute the DOCUMENT command with a valid input file 
specification. 

INVALID_VALUE , Cannot use file-spec as a file for /qualifier 
Fatal: The specified input file associated with the qualifier cannot be opened. 
User Action: Reexecute DOCUMENT command with a valid input file 
specification. 

NEED_VALUE , Destination entry parameter command needs /VALUE or a 

keyword 

Error: Syntax error found when parsing the destination data file. 


User Action: Refer problem to system manager. If you receive this message 
and are under a service contract with DIGITAL, call your customer service 
center. Otherwise, submit a Software Performance Report. 


NO_CONTENTS , No contents; /CONTENTS qualifier unnecessary 


Warning: No contents information was available to generate a contents file; 
no contents file will be produced. 


User Action: Do not use the /CONTENTS qualifier when processing 
this input file. An SDML file must contain at least one <CHAPTER> , 
<APPENDIX> , or <HEADx> tag to produce a table of contents file. 
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NO_INDEX , No index; /INDEX qualifier unnecessary 


Warning: No index information was available to generate an index file; no 
index file will be produced. 


User Action: Do not use the /INDEX qualifier when processing this input 
file. An SDML file must contain at least one <X> or <Y> tag to produce an 
index file. | 


OPEN_DESIGN , Error opening design data file in DOCS6STANDARD_ 
FORMATS 


Fatal: An error occurred when trying to open the DOC$STANDARD_. 
FORMATS:DOC$DESIGNS.DAT data file. 


User Action: Check for existence of DOC$STANDARD_ 
FORMATS:DOC$DESIGNS.DAT data file; if it exists, then check the file 
protection on that file. 


OPEN_DEST, Error opening DOC$STANDARD_ 
FORMATS:DOC$DESTINATIONS data file 


Fatal: There was an RMS error when trying to open the destination data file. 


User Action: Check for existence of DOC$STANDARD_— 
FORMATS:DOC$DESTINATIONS.DAT data file; if it exists, then check 
the file protection on that file. 


PGFLQ_TOO_LOW , Process paging file quota too low, required value is 
minimum-value 


Fatal: The PGFLQUOTA of the current process is not large enough to run the 
DOCUMENT command. 


User Action: Contact system manager to increase quota. 


PRINT_CONTENTS, [Printing Contents]... 


Informational: Indicates that your contents file is being sent to the 
designated print queue. 


User Action: None. 


PRINT_INDEX, [Printing Index]... 


Informational: Indicates that your index file is being sent to the designated 
print queue. 


‘User Action: None. 


THESE—DESIGNS , Choose one of these designs: 


Informational: Inquires for choice of document design types, this is required 
input to the DOCUMENT command. 


User Action: At the prompt, type the desired design from the choices offered. 
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THESE_DESTS , Choose one of these destinations: 


Informational: Inquires for choice of document destinations, this is required 
input to the DOCUMENT command. 


User Action: At the prompt, type the desired destination from the choices 
offered. 


TYPE_INPUT , input file 
Informational: Inquires for the input file. 


User Action: At the prompt, type the name of the input file. 


UNR_DESIGN , Unrecognized design - please check your spelling 


Fatal: An unrecognized design parameter has been specified to the 
DOCUMENT command. 


User Action: Reexecute the DOCUMENT command with a valid design 
parameter. 


UNR_DEST, Unrecognized destination - please check your spelling 


Fatal: An unrecognized destination parameter has been specified to the 
DOCUMENT command. 


User Action: Reexecute the DOCUMENT command with a valid destination 
parameter. 
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C.2 Tag Translator Messages 


ABORTFORE, at tag or text on line n of file 
file-spec 
There have been more than number error messages of severity 
level E 


Fatal: The tag translator did not produce an output file because it detected 
too many errors in the SDML source file with a severity level of Error. SDML 
defines the minimum number of error messages of severity E as 0, although 
this default value can be modified in local usage. 


User Action: Examine the output from the preceding messages to determine 
the errors you need to correct. 


ABORTFORW, | at tag or text on line n of file 
file-spec 
There have been more than number error messages of severity 
level W 


Fatal: The tag translator did not produce an output file because it detected 
too many errors in the SDML source file with a severity level of Warning. 
SDML defines the minimum number of error messages of severity W as 30, 
although this default value can be modified in local usage. 


User Action: Examine the output from the preceding messages to determine 
the errors you need to correct. 


ARGBADOPR, at tag or text on line n of file 
file-spec 
Argument 2 to tag <COUNTER> has an illegal arithmetic operator 


Warning: The tag translator has found an illegal operator. The second 
argument to the <COUNTER> tag consists of pairs of operators and operands, 
and an optional trailing comment. If you receive this message and are under a 
service contract with DIGITAL, call your customer service center. Otherwise, 
submit a Software Performance Report. 


User Action: Verify that the operators and the comment character are correct. 


ARGINCMPL, at tag or text on line n of file 
file-spec 
Argument 2 to tag <COUNTER> is incomplete. 


Warning: The tag translator has not found at least one operator and one 
operand. The second argument to the <COUNTER> tag requires at least 
one operator and one operand. If you receive this message and are under a 
service contract with DIGITAL, call your customer service center. Otherwise, 
submit a Software Performance Report. 


User Action: Verify that the second argument begins with an operator and 
an operand. 


ARGINVALD, at tag or text on line n of file 
file-spec 
Argument number to tag <tagname> is an invalid argument. 


Warning: The argument in the specified position is not valid for the specified 
tag. 


User Action: Verify the tag’s argument and correct it. 
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ARGMENTIS, The argument is string 


Informational: Follows a message that indicates that an argument is invalid, 
for example, when a numeric argument is required, but a character string 
argument is specified. 


User Action: Use the information to correct your source file. 


ARGMISSNG, at tag or text on line n of file 
file-spec 
Argument number to tag <tagname> is missing 


Warning: The tag translator found no text for the indicated argument, but 
the argument is required for the indicated tag. 


User Action: Supply a value for the indicated argument. 


ARGNOTCHRR, | at tag or text on line n of file 
file-spec 
Argument to tag <CHR> is not in the range 32 to 126 


Warning: The <CHR> built-in tag requires a numeric argument whose value 
is in the range of 32 to 126. If you receive this message and are under a 
service contract with DIGITAL, call your customer service center. Otherwise, 
submit a Software Performance Report. 


User Action: Correct the reference to the <CHR> built-in tag so that it 
specifies a value that is in the correct numeric range. 


ARGNOTKEY, at tag or text on line n of file 
file-spec 
Argument number to tag <tagname> is not a keyword 


Warning: The argument in the indicated position is not a valid keyword 
argument for the indicated tag. This message is generally followed by a 
message that shows the keyword that was specified. 


User Action: Using the information in this message and the accompanying 
message, determine the keyword in error. Check the VAX DOCUMENT User 
Manual, Volume 1 to determine the valid arguments for the tag in question 
and correct your source file. 


ARGNOTLET, at tag or text on line n of file 
file-spec 
Argument to tag <SET_APPENDIX_LETTER> is not a letter 
Warning: The <SET_APPENDIX_LETTER> tag requires a letter (A to Z). 


User Action: Correct the source file to supply a letter as the first character of 
the argument. 
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ARGNOTMSG, | at tag or text on line n of file 
file-spec 
Argument number to tag <tagname> is not a valid message 
code 


Warning: The indicated argument to the <TAG_DIAGNOSTIC> built-in tag is 
not a recognized message code. If you receive this message and are under a 
service contract with DIGITAL, call your customer service center. Otherwise, 
submit a Software Performance Report. 


User Action: Verify the spelling of the message code and correct your source 
file. 


ARGNOTNAM, at tag or text on line n of file 
file-spec 
Argument number to tag <tagname> is not a valid name 


Warning: The indicated argument does not obey the rules for formation of 
a name. A name must have only letters, digits and the underscore character. 
A name must not begin with two underscores. Spaces, tabs, and carriage 
returns are not allowed. 


User Action: Correct the argument so that the name is valid. 


ARGNOTNUM, | at tag or text on line n of file 
file-spec 
Argument number to tag <tagname> is not a number 


Warning: A non-numeric argument was specified to a tag that requires a 
numeric argument. 


User Action: Verify that the argument is in the correct position in the tag’s 
argument list. Supply a numeric argument to the tag. 


ARGNOTPOS, | at tag or text on line n of file 
file-spec 
Argument to tag 9<SET.CHAPTER_NUMBER> is not a positive 
integer 


Warning: The <SET_CHAPTER_NUMBER> tag requires a positive integer for 
the chapter number argument. 


User Action: Correct the source file to supply a positive integer. 


ARGNOTTYP, at tag or text on line n of file 
file-spec 
Argument string to tag <tagname> is not valid for doctype string 


Warning: The indicated argument is not valid for this tag in the indicated 
doctype. . 


User Action: Verify that you specified the correct doctype keyword on the 
DOCUMENT command line. 


ARGOUTRAN, | at tag or text on line n of file 
file-spec 
Argument number is not in the range 0 to 9 
Warning: The indicated argument cannot be less than 0 or greater than 9. 


User Action: Correct the argument so that the number is in range. 
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ARGOVREFLW, | at tag or text on line n of file 
file-spec 
More than number characters in an argument 


Fatal: The argument is too large. This often indicates that an argument 
list was not terminated correctly. The tag translator may be including large 
portions of the input text as part of the argument. 


User Action: Check the tag indicated by the location information and supply 
the correct termination to the argument list. 


AUXOVRFLW, at tag or text on line n of file 
file-spec 
More than number auxiliary files open 


Fatal: The number of auxiliary files that can be open simultaneously is 
limited. If you receive this message and are under a service contract with 
DIGITAL, call your customer service center. Otherwise, submit a Software 
Performance Report. 


User Action: Be sure to close an auxiliary file when you have finished 
reading or writing it. 


BADLSTARG, at tag or text on line n of file 
file-spec 
Argument string is not valid for <LIST> type string 


Warning: Verify the argument you specified to the <LIST> tag. Each type of 
list accepts different keyword arguments, for example, UPPERCASE is a valid 
keyword for alphabetic lists, but not for numbered lists. 


User Action: Verify that you have specified the correct type of list. If you 
specify a keyword argument, be sure that it is spelled correctly. 


BNOTESOUT, at tag or text on line n of file 
file-spec 
Accumulated string not referenced. 
Notes will not be output 


Warning: A document contained <BACK_NOTE> or <BIB_NOTE> tags, but 
no corresponding <BACK NOTES> or <BIB_NOTES> was specified to output 
the accumulated notes. 


User Action: Place the <BACK_NOTES> or <BIB_NOTES> tag in the source 
file at the position at which you want them output. 


BOXTOOBIG, at tag or text on line 1 of file 
file-spec 
Length number of boxed item exceeds number characters. 


Warn: An argument to the <BOX> tag exceeds the maximum number of 
characters allowed. The text will be output as null. 


User Action: Correct the <BOX> tag to specify an argument with fewer 
characters. 
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CALL_NEST, at tag or text on line n of file 
file-spec 
Callouts inaccurately nested in a monospaced example. 


Error: A monospaced example using callouts incorrectly nests 
<EXAMPLE> ... <ENDEXAMPLE> tags (or tags that produce monospaced 
output, such as <CODE_EXAMPLE> ) with respect to the <CALLOUTS> ... 
<ENDCALLOUTS> tags. For example, the following is incorrect: 


<CALLOUTS> (\PREFIX) 
<CODE_EXAMPLE> 


<ENDCALLOUTS> 
<ENDCODE_EXAMPLE> 


User Action: Correct the SDML source file so that the begin and end tags for 
the example and the callouts are correctly nested, for example: 


<CALLOUTS>(\PREFIX) 
<CODE_EXAMPLE> 


<ENDCODE_EXAMPLE> 
<ENDCALLOUTS> 


CANTOPINT, Cannot open intermediate input file: 
file_spec 


Fatal: The post translator cannot open the .int_tex file. 


User Action: Verify that the file specification is correct, and that you have 
sufficient resources and access rights to open the file. 


CANTOPOUT, Cannot create output file: 
file_spec 


Fatal: The post translator cannot create the .tex file for some reason. 


User Action: Verify that the file specification is correct, and that you have 
sufficient resources and access rights to create the file. 


CASOVRFLW, <CASE> tags have been nested beyond the limit of number 


Fatal: The <CASE> built-in tag has been nested beyond the allowed limit. 
Submit a Software Performance Report. 


User Action: Verify that the tag definition that uses the <CASE> or 
<CASE_NUMERIC> tag has been correctly coded. 


COMNOTEND, at tag or text on line 1 of file 
file-spec 
A <COMMENT> in a tag definition has not been terminated 


Error: A tag’s definition contains a comment that is not properly terminated. 


User Action: Examine the tag definition to be certain that the comment 
text is terminated. If the comment text contains characters such as 
ampersand, backslash, vertical bar, or parentheses, use the <COMMENT> ... 
<ENDCOMMENT> format. 
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CPU_USAGE, Pass 1: number Pass 2: number Total: number seconds 


Informational: The tag translator reports its CPU usage during pass 1 and 
pass 2 and the total for both passes. 


User Action: None. 


CPYNAMHID, at tag or text on line n of file 
file-spec 
<COPY_TAG> is referencing a tag ( <tagname> ) that is hidden 


Warning: The name referenced by the <COPY_TAG> is hidden, and therefore 
cannot be copied as a new tag definition. If you receive this message and are 
under a service contract with DIGITAL, call your customer service center. 
Otherwise, submit a Software Performance Report. 


User Action: Be sure that the name is spelled correctly and that the sequence 
of tag executions allows the copy to take place when the tag is not hidden. 


CPYNAMUND, §at tag or text on line n of file 
file-spec 
<COPY_TAG> is referencing a name (string) that is undefined 


Warning: The name referenced by the <COPY_TAG> is not defined, and 
therefore cannot be copied as a new tag definition. If you receive this message 
and are under a service contract with DIGITAL, call your customer service 
center. Otherwise, submit a Software Performance Report. 


User Action: Be sure that the name is spelled correctly and that the tag is 
already defined. 


DEFSLOADD, End of Loading of Tag Definitions 


Informational: This message is issued after the tag definitions have been 
loaded and before the reading of any input files. If any error messages appear 
before this message, the errors were detected during the loading of the tag 
definitions. 


User Action: None. 


DIVBYZERO, at tag or text on line n of file 
file-spec 
Argument 2 to tag <COUNTER> is attempting to divide by zero 


Warning: Division by zero is undefined. (Processing continues. The result 
is as if a divisor of 1 had been used.) If you receive this message and are 
under a service contract with DIGITAL, call your customer service center. 
Otherwise, submit a Software Performance Report. 


User Action: Verify that the correct divisor is specified. You may want to use 
the <COMPARE_NUMERIC> built—in tag to test the divisor before using it. 
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DUPHIDNAM, | at tag or text on line n of file 


file-spec 
A <HIDE_TAGS> tag is reusing the hide-name, string 


Warning: The hide-name is already in use. Once tags have been hidden 
under a specific hide-name that hide-name cannot again be used until the 
tags have been revealed with the <REVEAL_TAGS> tag. If you receive this 
message and are under a service contract with DIGITAL, call your customer 
service center. Otherwise, submit a Software Performance Report. 


User Action: Examine the sequence in which <HIDE_TAGS> and <REVEAL— 
TAGS> tags are invoked using the indicated hide-name. Correct the sequence 
so that the hide and reveal actions alternate in sequence. 


DUPSYMBOL, at tag or text on line n of file 
file-spec 
The symbol string is being defined twice. 
The earlier definition is replaced by the new definition 


Warning: The same symbol is being defined for two different purposes. The 

tag translator requires that each symbol be unique. If your symbols exceed 31 
characters in length, the automatic truncation to 31 characters may be causing 
two different symbols to look alike. 


User Action: Verify that both symbols are defined uniquely within the first 
31 characters. 


ENDNOTBEG, | at tag or text on line n of file 
file-spec 
<tagname> specified without corresponding <tagname> . 


Warn: A terminating tag was specified without the tag that it terminates. The 
tag is ignored. 


User Action: Verify that you correctly entered the beginning tag. Or, remove 
the extraneous ending tag from your source file. 


ENDPASS_1, End of first pass over the input 


Informational: The tag translator reports the end of the first pass over all 
input files. Error messages that appear ahead of this message were issued 
during the first pass. Error messages that follow this message are issued 
during the second pass over the input files. 


User Action: None. 


EOFARGLST, End of file encountered while searching for closing 


parenthesis. See argument list of tag <tagname> on line number 
of file 
filename 


Fatal: An argument list is not terminated before the end of the current input 
file. Either a right parenthesis is missing, or an <INCLUDE> tag occurred in a 
tag’s argument list. 


User Action: Verify that the indicated tag’s argument list is terminated, and 
that no tag’s argument list is unterminated at the end of an included file. 
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EOFCOLECT, End of file encountered while searching for tag <tagname> . 
See <COLLECT> tag on line number of file 
filename 


Fatal: A <COLLECT> built-in tag has encountered an end of file before 

encountering the indicated stop-tag. If you receive this message and are 
under a service contract with DIGITAL, call your customer service center. 
Otherwise, submit a Software Performance Report. 


User Action: Verify the spelling of the stop-tag argument, and the presence 
of the stop-tag in the input file. 


EOFENDCAS, End of file encountered while searching for tag <ENDCASE> . 
See <CASE> or <CASE_NUMERIC> tag on line number of file 
filename 


Fatal: A <CASE> (or <CASE_NUMERIC> ) built-in tag is not terminated 
before the end of file. If you receive this message and are under a service 
contract with DIGITAL, call your customer service center. Otherwise, submit 
a Software Performance Report. 


User Action: Verify that every <CASE> and <CASE_NUMERIC> built-in tag 
is terminated by an <ENDCASE> tag, even if the <CASE> built-in tags are 
nested. 


EOFENDCOM, End of file encountered while searching for tag <ENDCOMMENT> . 
See <COMMENT> tag on line number of file 
filename 


Fatal: Comment text, introduced by the <COMMENT> built-in tag, was not 
enclosed as an argument, and therefore requires an <ENDCOMMENT> tag as 
a terminator. 


User Action: Verify that the comment text is either enclosed as an 
argument to the <COMMENT> built-in tag, or that it is terminated with 
an <ENDCOMMENT> tag. 


EOFENDLIT, End of file encountered while searching for <ENDLITERAL> 
-Or <ENDDELAYED>. See <LITERAL> or <DELAYED> tag on line 
number of file 
filename 


Fatal: Literal text, introduced by the <LITERAL> or <DELAYED> tag, was 
not enclosed as an argument, and therefore requires an <ENDLITERAL> or 
<ENDDELAYED> tag as a terminator. 


User Action: Verify that the literal text is either enclosed as an argument 
to the <LITERAL> or <DELAYED> tag, or that it is terminated with an 
<ENDLITERAL> or <ENDDELAYED> tag. 


EOFIGNORE, at tag or text on line n of file 
file-spec 
End of file encountered while searching for tag or label 


Fatal: An <IGNORE> built-in tag has encountered the end of the input file 
without finding one of the tags or labels supplied in the argument list. If you 
receive this message and are under a service contract with DIGITAL, call your 
customer service center. Otherwise, submit a Software Performance Report. 


User Action: Verify the spelling of the tags and labels in the argument list. 
You may want to add the label __EOF to the argument list. 
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ERRCLSINP, at tag or text on line n of file 
file-spec 
Input files not closed at end of pass. 


Fatal: Files that were included as part of the input have not been properly 
closed. 


User Action: Submit a Software Performance Report. 


ERRDEFLNM, at tag or text on line n of file 
file-spec 
Attempt to define logical name was unsuccessful 
Logical: string 
Equivalence: string 


Warning: An <INCLUDES_FILE> tag in the <PROFILE> template has failed in 
its attempt to define the logical name with the given equivalence string. 


User Action: Examine the arguments to the <INCLUDES_FILE> tag to ensure 
that they are a correctly formed name and a file specification. Correct the 
<INCLUDES_FILE> arguments. 


ERRDURGET, at tag or text on line n of file 
file-spec 
Error reading line number of file: 
filename. 
Perhaps the line is too long 


Warning: The indicated line probably exceeds the tag translator’s buffer size. 
Processing continues with a truncated line (which may introduce other errors 
if the information that was lost includes part of an argument list to a tag). 


User Action: Edit the input file and shorten the line, or break it into two 
lines if possible. 


ERRDURPUT, at tag or text on line n of file 
file-spec 
Error detected writing output file: 
filename 


Fatal: An error was detected while attempting to write to the indicated output 
file. 


User Action: Check that your process has sufficient privilege and access 
rights and that the output device has sufficient free space to hold the file. 


ERROPEAUX, | at tag or text on line n of file 
file-spec 
Cannot open auxiliary file: 
filename 


Warning: An attempt to open an auxiliary file failed. The next Informational 
message may supply the reason for the failure. Processing continues, but 
attempts to read or write the auxiliary file will fail and will generate error 
messages. If you receive this message and are under a service contract with 
DIGITAL, call your customer service center. Otherwise, submit a Software 
Performance Report. 


User Action: If the file is being opened for input, verify that the correct file is 
being accessed and can be read. If the file is being opened for output, verify 
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that the file specification is correct, and that you have sufficient resources and 
access rights to create the file. 


ERROPEDMP, at tag or text on line n of file 
file-spec 
Cannot open dump file: 
filename 


Warning: The <RETRIEVE> built-in tag has failed to open a file for output. 
The next Informational message may indicate the reason for the failure. If 
you receive this message and are under a service contract with DIGITAL, 
call your customer service center. Otherwise, submit a Software Performance 
Report. 


User Action: Verify that the file specification is correct, and that you have 
sufficient resources and access rights to create the file. 


ERROPEINC, at tag or text on line n of file . 
file-spec 
Cannot open included file: 
filename 


Warning: The indicated file cannot be opened for input. The next 
Informational message may indicate the reason for the failure. Processing 
continues without the included file. 


User Action: Verify that the correct file is being accessed and can be read. If 
you are using a logical name to access the file, verify that the logical name 

is defined. If you are relying on an <INCLUDES_FILE> tag to define the 
logical name, verify that the spelling of the logical name is the same in the 
<INCLUDES_FILE> tag, and that the <INCLUDES_FILE> tag has been specified 
for the book element that contains the <INCLUDE> tag. 


ERROPEINP, at tag or text on line n of file 
file-spec 
Cannot open input file: 
filename 


Fatal: The input file specified on the command line cannot be opened. The 
next Informational message may indicate the reason for the failure. 


User Action: Verify that the correct file is being accessed and can be read. 


ERROPELOG, at tag or text on line n of file 
file-spec 
Cannot open log file: 
filename 


Warning: The <SET> built-in tag has failed to open a file for trace output. 
The next Informational message may indicate the reason for the failure. If 
you receive this message and are under a service contract with DIGITAL, 
call your customer service center. Otherwise, submit a Software Performance 
Report. 


User Action: Verify that the file specification is correct, and that you have 
sufficient resources and access rights to create the file. 
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ERROPEOUT, §at tag or text on line n of file 
file-spec 
Cannot open output file: 
filename 


Fatal: The tag translator cannot open the output file. The next Informational 
message may indicate the reason for the failure. 


User Action: Verify that the file specification is correct, and that you have 
sufficient resources and access rights to create the file. 


ERROPESEC, at tag or text on line n of file 
file-spec 
Cannot open secondary output file: 
filename 


Warning: An attempt to open a secondary output file failed. Processing 
continues, but output will go to the primary output file. If you receive this 
message and are under a service contract with DIGITAL, call your customer 
service center. Otherwise, submit a Software Performance Report. 


User Action: Verify that the file specification is correct, and that you have 
sufficient resources and access rights to create the file. 


ERROPESIN, at tag or text on line n of file 
file-spec 
Cannot open cross reference input file: 
filename 


Fatal: The tag translator failed to open the file that contains the symbols used 
for cross-references. The next Informational message indicates the reason for 
the failure. 


User Action: The file that contains the symbols used in cross-referencing can 
be used by only one user at a time. The tag translator locks the file to ensure 
that users have only serial access to it. If the reason for the failure to open 
the file was due to the fact that another user was currently using the file, you 
must wait and reissue the command when the file is no longer in use. 


ERROPESOT, at tag or text on line n of file 
file-spec 
Cannot open cross reference output file: 
filename 


Fatal: The tag translator failed to open a file for writing the symbols used for 
cross-references. The next Informational message may indicate the reason for 
the failure. 


User Action: Verify that you have sufficient resources and access rights to 
create the file. 


ERRPRSFSP, at tag or text on line n of file 
file-spec 
Error parsing file specification: 
filename 


Warning: The file specification contains an error. 


User Action: Correct the file specification or logical name definition. 
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ERRVMZONE, at tag or text on line n of file 
file-spec 
Internal error. Failure to create VM zone. 


Fatal: The tag translator failed to create space in virtual memory for storage 
of data. 


User Action: Submit a Software Performance Report. 


EXAMINLIN, Examine line number of file filename 


Informational: This message follows other messages of greater severity, and 
directs you to a possible error in the input. 


User Action: Use the information to examine and correct your input. 


EXFOOTNOT, at tag or text on line n of file 
file-spec 
Footnotes in a monospaced example exceed maximum of 4. 


Warning: You have specified more than four <FOOTNOTE> tags ina 
<CODE_EXAMPLE> or other monospaced example. The maximum allowed is 
four. The footnote will not be processed. 


User Action: Correct the source file by removing the extraneous footnotes. 


EXPAPPLET, Explicit appendix letter string set on line number of file 
filename 


Informational: This message warns that the letter assigned to the next 
<APPENDIX> tag has been supplied explicitly by a <SET_APPENDIX_LETTER> 
tag. The appendixes may be lettered out of sequence. 


User Action: No action is required. 


EXPAPPNUM, Explicit appendix number number set on line number of file 
filename 


Informational: This message warns that the number assigned to the next 
<APPENDIX> tag has been supplied explicitly by a <SET_APPENDIX— 
NUMBER> tag. The appendices may be numbered out of sequence. 


User Action: No action is required. 


EXPCHAPNO, Explicit chapter number number set on line number of file 
filename 


Informational: This message warns that the number assigned to the next 
<CHAPTER> tag has been supplied explicitly by a <SET_CHAPTER_NUMBER> 
tag. The chapters may be numbered out of sequence. 


User Action: No action is required. 


FILEWRTNG, File filename written (0 length) 


Informational: An Error or Fatal message has been issued during the tag 
translation of a book element. The output file for that book element is 
reduced to 0 length. 


User Action: Correct the problems indicated in the Error and Fatal messages 
and reprocess. 
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FILEWRTOK, File filename written 


Informational: An element of a book has been processed through the tag 
translation phase. 


User Action: None. 


FCMDPARMS, | at tag or text on line n of file 
file-spec 
<tagname> specified without <tagname> in Format. 
Using <tagname> alone 


Warning: The tags <FCMD> and <FPARMS> must be used together to 
produce predictable results. 


User Action: Modify your source file so that it contains both the <FCMD> 
and <FPARMS> tags. Arguments to either of these tags may be null, that is, 
it is valid to specify <FCMD>. 


FIG_DEPTH, at tag or text on line n of file 
file-spec 
Tag <tagname> value number exceeds the maximum NUMBER or 
is 0. 


Warning: The indicated tag specifies a depth for a figure or space to be left 
for a figure that will overrun the page boundaries. Or, the argument was 
specified as 0. In either case, the document’s default full page depth will be 
used. 


User Action: Correct the tag so that you specify no more than the maximum 
allowed. 
FIG_WIDTH, at tag or text on line n of file 
file-spec 
Tag <tagname> value number exceeds the maximum NUMBER or 
is 0. 


Warning: The indicated tag specifies a width for a figure or space to be left 
for a figure that will overrun the page boundaries. Or, the argument was 
specified as 0. In either case, the document’s default full page width will be 
used. 


User Action: Correct the tag so that you specify no more than the maximum 
allowed. 


FIGINDENT, at tag or text on line n of file 
file-spec 
The value number specified for a block indent exceeds the 
current allowed maximum of number. 


Warning: A <FIGURE_FILE> tag specified the INDENT argument and a value 
that exceeds the current maximum allowed. The maximum value will be 
used. 


User Action: Correct the numeric argument specified with INDENT so that it 
does not exceed the indicated maximum. 
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FIGLINMAX, at tag or text on line n of file 
file-spec 
Monospaced example lines in <tagname> exceed maximum 
number. 


Error: A monospaced example specified in the context of a <FIGURE> or 
<EXAMPLE> tag is too long to fit on the current page and either no <VALID_ 
BREAK> tags were specified to provide valid break points, or there are too 
many lines between <VALID_BREAK> tags. 


User Action: Put <VALID_BREAK> tags at suitable places in the monospaced 
example to allow the pages to break automatically. 


FILENUMNG, | at tag or text on line n of file 
file-spec 


File number is out of range 


Warning: A number supplied to the <FILE_NAME> tag is not within the 
range of 1 to the number of files that have been opened. If you receive this 
message and are under a service contract with DIGITAL, call your customer 
service center. Otherwise, submit a Software Performance Report. 


User Action: Do not attempt to pass a number to the <FILE_NAME> tag 
unless that number was previously returned by an invocation of the <FILE— 
NUMBER> tag. This guarantees that only legal file numbers will be used as 
arguments to the <FILE_NAME> tag. 


FILISOPEN, at tag or text on line n of file 
file-spec 
Auxiliary file: 
filename 
is already open 


Warning: An <OPEN> built-in tag is specifying a file that is already open. 
The request is ignored, and processing continues. If you receive this message 
and are under a service contract with DIGITAL, call your customer service 
center. Otherwise, submit a Software Performance Report. 


User Action: Check the file specification to be sure that the correct file is 
being specified. Remove the second request to open the same file. 


FILNOTOPN, | at tag or text on line 1 of file 
file-spec 
Auxiliary file: 
filename 
is not open 


Warning: A <READ> or <WRITE> built-in tag is addressing a file that 

has not been opened. If you receive this message and are under a service 
contract with DIGITAL, call your customer service center. Otherwise, submit 
a Software Performance Report. 


User Action: Verify that the file is being correctly referenced and that the file 
has been opened with the <OPEN> built-in tag. 
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FMTDEVICE, Tag <tagname> produces device-specific output. 


Informational: A tag that produces specific formatting controls has been 
processed. The output may not be suitable if the file is processed for another 
document type, destination, or both. For example, <FINAL—CLEANUP> (LINE_ 
BREAK) tells the text processor to create a new line of output, but the line 
break may not be suitable on all output devices. 


User Action: Use explicit formatting commands sparingly. 


GTMAXARGS, at tag or text on line n of file 


file-spec 
More than number arguments supplied to tag <tagname> 


Error: The indicated tag does not expect more than the indicated number 
of arguments. Perhaps you included a backslash character in one of the 
arguments, which the tag translator interpreted as an argument separator. 


User Action: Verify that the argument list is correctly coded. If necessary, 
use the <BACKSLASH> tag to code a backslash character that is actually part 
of an argument. 


HIDNOTHID, at tag or text on line n of file 
file-spec 
Internal error. A hidden tag was invoked, 
but was not found in the data structure of hidden tag names 


Fatal: The algorithm for hiding and revealing tags has failed. If you receive 
this message and are under a service contract with DIGITAL, call your 
customer service center. Otherwise, submit a Software Performance Report. 


User Action: Submit a Software Performance Report. 


ICON_TEXT, at tag or text on line n of file 
file-spec 
No text supplied for <ICON>. 


Warning: An <ICON> tag was specified, but no <ICON_TEXT> tag specified 
text to accompany the graphics. No text will be output. 


User Action: Verify that you specified <ICON_TEXT> correctly. 


IGNAMEILL, at tag or text on line n of file 
file-spec 
Argument string to <IGNORE> is illegal 
Warning: The argument is not a legal name or label. The argument is 
dropped from the argument list, and processing continues. If you receive this 


message and are under a service contract with DIGITAL, call your customer 
service center. Otherwise, submit a Software Performance Report. 


User Action: Examine the argument list to the <IGNORE> tag. 


Messages 
Tag Translator Messages 


IGNAMEMIS, at tag or text on line n of file 
file-spec 
An argument to <IGNORE> tag is a null string 


Warning: One of the arguments to an <IGNORE> tag is empty. If you 
receive this message and are under a service contract with DIGITAL, call your 
customer service center. Otherwise, submit a Software Performance Report. 


User Action: Examine the argument list to the <IGNORE> tag. The tag 
names should not have brackets around them. 


IGNORESET, Ignoring <SET_CHAPTER-NUMBER> or <SET_APPENDIX—LETTER> 
on line number of file 
filename 


Informational: The <SET.CHAPTER_NUMBER> and <SET_APPENDIX_LETTER> 
tags are ignored when doing a book build or element build, because the 
numbering of book elements is done automatically. 


User Action: Remove the tag. 


IGNOTDONE, §at tag or text on line 1 of file 
file-spec 
The <IGNORE> tag has no arguments, so it is ignored 


Warning: Missing or illegal arguments have resulted in an <IGNORE> tag 
that has no legal arguments. The <IGNORE> tag is not executed. If you 
receive this message and are under a service contract with DIGITAL, call your 
customer service center. Otherwise, submit a Software Performance Report. 


User Action: Examine the argument list to the <IGNORE> tag. 


INCNOTARG, at tag or text on line n of file 
file-spec 
An <INCLUDE> tag cannot be invoked in an argument 


Error: An <INCLUDE> tag can be invoked only in text. 


User Action: Move the <INCLUDE> tag outside the argument list. 


INCOVRFLW, at tag or text on line n of file 
file-spec 
More than number nested levels of included files 


Fatal: The number of included files that can be open at the same time is 
limited. The limit has been exceeded. 


User Action: Consider whether the included files can be included 
sequentially rather than simultaneously. If file A includes file B, and file 

B includes file C, consider whether file A can include both B and C, one after 
the other. 


INDENTVAL, at tag or text on line n of file 
file-spec 
The <tagname> specifies an indent value of number. 
This exceeds the maximum number allowed for this tag. 


Warning: The INDENT argument to the specified tag specified an indent 
value that exceeds the maximum allowed. The maximum value will be used. 


User Action: Correct the tag to specify an indent value less than or equal to 
the maximum allowed. 
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INT_LOGIC, at tag or text on line n of file 
file-spec 
Internal error processing tag <NAME> 


Error: An SDML tag definition has an error in it. 


User Action: Submit a Software Performance Report. 


ISTHISTAG, at tag or text on line n of file 
file-spec 
Ignoring <string. Is this a tag without a closing angle bracket? 


Warning: An apparent tagname has been found, but without the closing 
angle bracket that is needed to make it a complete tag invocation. This 
sometimes occurs when an underscore is typed as a hyphen. For example, 
<TABLE_SETUP> is typed as <TABLE-SETUP>. The tag translator stops on the - 
hyphen because that is an illegal character in a tagname, and it assumes that 
you may have meant to type <TABLE> -. 


User Action: If this is a typo, simply add the closing angle bracket or change 
the hyphen to an underscore. If this is not a typo (you really want the left 
angle bracket and the tagname to appear in the output), use the <LITERAL> 
tag to enclose the left angle bracket. This action will suppress the warning 
message. 


KEYPADROW, | at tag or text on line 1 of file 
file-spec 


Too many keypad rows. Extra rows ignored 


Warning: A set of tags within a <KEYPAD_SECTION> specifies more than 
four <KEYPAD_ROW> tags. The keyboard keypad has only four rows and 
one end row. 


User Action: Determine which <KEYPAD_ROW> tag is extra and remove it 
from your source file. 


LASTAGWAS, Last occurrence of <tagname> was on line number 


Informational: This message is issued when a tag is not ended before a 
particular context or the end-of-file. It tells you the line number of the last 
occurrence of the tag. 


User Action: Use the indicated line number to determine where to correct 
your source file. 


LISTYPWAS, List type was string 


Informational: This message accompanies an error that indicates that a 
<LIST> tag was not terminated. It indicates the type of list, for example, 
NUMBERED, UNNUMBERED, and so on. 


User Action: Use this information to correct your SDML source file. 
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LITOVRFLW, More than number characters in literal. See line number of file 
filespec 


Fatal: The size of the text encompassed by a <LITERAL> or <DELAYED> tag 
is limited. This error may indicate that a <LITERAL> or <DELAYED> tag was 
incorrectly terminated. 5 


User Action: Verify that the <LITERAL> or <DELAYED> tag has been 
correctly coded. If the text to be encompassed by the tag exceeds the limit, 
you must break it up and use more than one <LITERAL> or <DELAYED> tag. 


LTMINARGS, at tag or text on line n of file 
file-spec 
Fewer than number arguments supplied to tag <tagname> 


Error: The indicated tag requires a minimum number of arguments. Perhaps 
one of the arguments has an unmatched right parenthesis in it, and the tag 
translator has treated that character as the terminator of the argument list. 


User Action: Review and correct the argument list. Be sure that the open 
parenthesis for the argument list is not preceded with a space, for example 
<TAG> (ARG) should be <TAG> (ARG). 


MARKUNBAL, | at tag or text on line n of file 
file-spec 
<MARK> tags are unbalanced. 


Error: A <MARK> tag and its corresponding <ENDMARK> tag cross a tag’s 
boundary or are incorrectly nested with respect to another pair of tags. For 

example, if a <MARK> tag is specified before <FORMAT> and <ENDMARK> 
is specified before <ENDFORMAT> , the tags are considered unbalanced. 


User Action: Look at the source file location of the indicated tag, and move 
it. In particular look for instances where a <MARK> tag is specified in a tag 
argument, but the <ENDMARK> tag is specified outside that tag’s argument 
or in an argument to another tag. 


MINEXCMAX, at tag or text on line n of file 
file-spec 
Minimum argument count (number) exceeds maximum argument 
count (number). 
(Minimum argument count is being reset to zero) 


Warning: A <DEFINE> or <REDEFINE> tag is specifying a minimum and 
maximum number of arguments and the minimum exceeds the maximum. 

If you receive this message and are under a service contract with DIGITAL, 
call your customer service center. Otherwise, submit a Software Performance 
Report. 


User Action: Correct the minimum and maximum argument values. 
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MSGIDISNG, at tag or text on line n of file 
file-spec 
The message identification string is invalid. 
The <HIDE_TAGS> tag is ignored 


Warning: The second argument to a <HIDE_TAGS> tag is supplying an 
unknown message identification. If you receive this message and are under a 
service contract with DIGITAL, call your customer service center. Otherwise, 
submit a Software Performance Report. 


User Action: Check the spelling of the message identification argument to be 
sure that it agrees with one of the error messages in the message file. 


NAMETRUNCG, at tag or text on line n of file 
file-spec 
Name string exceeds 31 characters. 
Name string is truncated version 


Warning: Names may not exceed 31 characters in length. The name that was 
supplied is a legal name, but it is too long. It is truncated to 31 characters. 


If more than one name is truncated, the shortened names may not be unique 
and other errors may occur depending on the type of name. 


User Action: Shorten this name (and any other names that are too long) to 
31 characters or less, so that there is no potential for other errors. 


NAME2LONG, | at tag or text on line n of file 
file-spec 
Condition name string exceeds 28 characters 


Error: Condition names may not exceed 28 characters in length. 


User Action: Shorten this name (and any other condition names that are too 
long) to 28 characters or less. 


NESTEDCOM, A <COMMENT> tag on line number of file 
filename 
is nested within <COMMENT> ... <ENDCOMMENT> that starts on 
line number of file 
filename 


Warning: <COMMENT> tags cannot be nested. 


Sometimes an error is made in typing a <COMMENT> tag in the format 
<COMMENT> (text). The typo makes it appear that the tag does not have an 
argument list, and it is assumed that an <ENDCOMMENT> tag is present to 
end the comment text. During the search for the <ENDCOMMENT> tag, if 
another <COMMENT> tag, is encountered it will appear to be nested within 
the first <COMMENT> tag’s text. 


User Action: Correct any typographical errors in the initial <COMMENT> tag 
or remove the nested <COMMENT> tag. 


C-27 


Messages 
Tag Translator Messages 


NODEFITEM, | at tag or text on line n of file 
file-spec 
Definition list specified no items before <tagname> . 


Warning: A <DEFINITION_LIST> tag, or a corresponding tag in the 
SOFTWARE doctype, was specified but no <DEFLIST.ITEM> / <DEFLIST_ 
DEF> tags were specified for the list. No output will be produced. 


User Action: Remove the definition list start/end tags; or provide item text 
for the definition list. 


NOENDPROF, _§at tag or text on line n of file 
file-spec 
The <PROFILE> tag was not terminated by an <ENDPROFILE> 
tag 


Warning: In order for the bookbuild process to be completed, the <PROFILE> 
tag must be terminated by an <ENDPROFILE> tag. The <ENDPROFILE> tag is 
supplied by default in this case. 


User Action: If the <PROFILE> tag is not terminated by an <ENDPROFILE> 
tag, add one after the final <ELEMENT> or <INCLUDES_FILE> tag. 


NOFIGELMS, at tag or text on line n of file 
file-spec 
<tagname> has no elements. 


Warning: A <FIGURE> or <EXAMPLE> tag was specified and terminated 
but there were no elements (for example, <FIGURE_SPACE> ), to place in the 
figure. 


User Action: Verify that you correctly spelled and entered tags for the figure 
or example. _ . 


NOHIDERVL, at tag or text on line n of file 
file-spec 
Ignoring request to hide the <REVEAL_TAGS> tag 


Warning: The <REVEAL_TAGS> built-in tag cannot be hidden by the action 
of a <HIDE_TAGS> built-in tag. If you receive this message and are under a 
service contract with DIGITAL, call your customer service center. Otherwise, 
submit a Software Performance Report. 


User Action: Remove the word REVEAL_TAGS from the argument list of 
the <HIDE_TAGS> tag. 


NONESTING, | at tag or text on line n of file 
file-spec | 
Invalid attempt to nest tag <tagname> . Ignored 
Warning: A tag is referenced when its context is already active. For example, 


this message is issued when <CODE_EXAMPLE> is specified when a previous 
<CODE—EXAMPLE> is not terminated. 


User Action: The indicated tag is ignored; however, you should verify your 
source file to determine whether the tag is a duplicate or whether, in fact, you 
did not terminate an earlier occurrence of the same tag. 
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NONEWEILE, at tag or text on line n of file 
file-spec 
<tagname> specified without string. No new file will be 
generated. 


Warning: A <CONTENTS_FILE> or <INDEX_FILE> was encountered in the 
input file, but the corresponding /CONTENTS or /INDEX qualifier was not 
present on the command line. No new contents or index will be produced. 
An earlier version of a contents or index file, if it exists, may be included in 
the output. 


User Action: If you want to include the current table of contents or index 
file, you should reissue the DOCUMENT command using the appropriate 
qualifier. 


NOPROFILE, at tag or text on line n of file 


file-spec 
Tag can appear only following a <PROFILE> tag 


Fatal: The tag is part of a profile and can be used only in that context and 
only within the same file as the <PROFILE> tag. 


User Action: Check that the tag appears after a <PROFILE> tag, and in the 
same file as the <PROFILE> tag. 


NOREADOUT, _§at tag or text on line n of file 
file-spec 
Cannot read from file: 
filename 
The file is opened as output 


Warning: A <READ> built-in tag cannot be addressed to an auxiliary file 
that is opened as output. (The <OPEN> tag defaults to output mode unless 
INPUT is specified.) If you receive this message and are under a service 
contract with DIGITAL, call your customer service center. Otherwise, submit 
a Software Performance Report. 


User Action: Correct the <OPEN> built-in tag to open the file as input. 





Tag <tagname> is not allowed in the string doctype 


Error: The indicated tag is not meaningful in the context of the doctype 
specified on the command line and cannot be processed. For example, the 
LETTER doctype does not allow <CHAPTER> or heading-level tags. 


User Action: Verify that you specify the correct doctype keyword on the 
DOCUMENT command line. If the doctype is correct, remove the tags from 
the SDML source file. 
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NOTHIDNAM, | at tag or text on line n of file 
file-spec 
A <REVEAL_TAGS> tag is referencing an unknown hide-name, 
string 


Warning: The hide-name specified by a <REVEAL_TAGS> tag is not in use. 
If you receive this message and are under a service contract with DIGITAL, 
call your customer service center. Otherwise, submit a Software Performance 
Report. 


User Action: Examine the sequence in which <HIDE_TAGS> and <REVEAL_ 
TAGS> tags are invoked using the indicated hide-name. Correct the sequence 
so that the hide and reveal actions alternate in sequence. 


NOTINELEM, | at tag or text on line n of file 
file-spec 
Tag can appear only within the context established by 
an element heading tag such as <CHAPTER>, <PART> , etc 


Error: When a bookbuild is done, all text and the tags that accompany the 
text must appear within some element of the book. The text and tags must 
follow the element heading tag in order to be considered to be in the context 
of the element. 


User Action: Correct the source text so that the tag that is in error follows a 
tag that heads an element of the book. 


NOTINPROF, at tag or text on line n of file 
file-spec 
The <tagname> tag must appear in the same file as the 
<PROFILE> tag 


Error: All the tags that make up a profile must appear in the same file. 


User Action: Move the tag into the same file as the <PROFILE> tag. 


NOZONEYET, at tag or text on line n of file 
file-spec 
Tag <tagname> _ specified outside its valid zone or context. 
It must be preceded by tag <tagname> . 


Error: A tag was specified outside the context that enables it, for example, a 
<COPYRIGHT_PAGE> tag was specified when the tag <FRONT_MATTER> has 
not been specified to enable the front matter zone. 


User Action: Be sure that you have specified the correct tag. Add the 
appropriate zone-enabling tag. 


NOWRITEIN, at tag or text on line n of file 
file-spec 
Cannot write to file: 
filename 
The file is opened as input 


Warning: The <WRITE> built-in tag cannot write to an auxiliary file that has 
been explicitly opened as input. If you receive this message and are under a 
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service contract with DIGITAL, call your customer service center. Otherwise, 
submit a Software Performance Report. 


User Action: Correct the <OPEN> built-in tag or use the proper tag 
(<READ> or <WRITE> ) to agree with the mode in which the file has been 
opened. 


NOUNDEFBI, at tag or text on line n of file 
file-spec 
Ignoring <UNDEFINE> or <REDEFINE> of the built-in definition of 
<tagname> 


Warning: A tag translator built-in tag cannot be deleted by the action of a 
<REDEFINE> or <UNDEFINE>. The built-in tag can be “stacked” by issuing 
a <DEFINE> tag for it, however. If you receive this message and are under a 
service contract with DIGITAL, call your customer service center. Otherwise, 
submit a Software Performance Report. 


User Action: Change a <REDEFINE> to a <DEFINE>. Change an 
<UNDEFINE> to a <DEFINE> that has an empty definition. 


NUMBERARG, at tag or text on line n of file 
file-spec 
Argument number is not valid for <tagname> . 
Warning: The numeric argument is not valid for the tag. 


User Action: Consult the tag’s documentation to determine the valid values. 


NUMLTZERO, The argument is less than 0. 


Informational: This message accompanies a message about an invalid 
numeric argument; it indicates that a negative value was specified for a tag 
argument which must be a positive number. 


User Action: Consult the tag’s documentation to determine the valid values. 


OTL_TITLE, at tag or text on line n of file 
file-spec 
<tagname> not valid within outlines. 
Enter the title as an argument to the <OUTLINE> tag 


Warning: A <TITLE> tag was specified within the context of the 
<OUTLINE> tags. 


User Action: Correct your source file so that the title of the outline is 
supplied in arguments to the <OUTLINE> tag. 


OTL—LEVEL, at tag or text on line n of file 
file-spec 
Outline level specified, number, is not in range 
The argument must specify 1 through 6 


Warning: An invalid number was specified in a <LEVEL> tag in an outline. 
Only levels of 1 through 6 are valid. 


User Action: Correct your source file so that no outline level has a number 
greater than 6. 
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OUTLIN2BG, at tag or text on line n of file 
file-spec 
Output line exceeded number bytes, and had to be broken 


Warning: Text in an output line exceeded the tag translator’s buffer. No text 
was lost because the line was written as two lines, but the division into two 
lines may have broken a word into two words, or interfered with the correct 
formatting of the text. This usually happens when the tag translator inserts a 
great many formatting commands into an output line. It also happens when 
a tag reference on a long input line is replaced by a very long string of text. 


User Action: Check the formatted output that corresponds to the input line 
specified in the location information to see if breaking the line affected the 
formatting. 


POSTERROR, at tag or text on line n of file 
file-spec 
Error encountered during post-translation 


Fatal: An error has been detected during the final step in tag translation. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


PQLISNONE, at tag or text on line n of file 
file-spec 
<tagname> specifies NONE’ when no heading is specified 


Warning: The keyword argument “NONE” was specified to a 
<PARAMDEFLIST> or <QUALDEFLIST> tag in a context in which no default 
heading is in effect. The use of NONE in this context is meaningless. 


User Action: Determine if you intended to be using default headings for 
the <PARAMDEFLIST> or <QUALDEFLIST> tag. If not, remove the tag from 
your source file. Otherwise, verify whether you should have invoked one 
of the reference templates to set an environment for parameter /qualifier list 
descriptions. 


PROFORDER, at tag or text on line n of file 
file-spec 
<PROFILE> tag is out of order. 


Fatal: A <PROFILE> tag has been detected after an element heading tag, 
such as <CHAPTER> . 


User Action: Place a single <PROFILE> ... <ENDPROFILE> sequence ina 
file by itself in order to do a bookbuild. 


PROFQ_ILL, at tag or text on line n of file 
file-spec 
/PROFILE qualifier illegal during a bookbuild 
Fatal: The /PROFILE qualifier was supplied on the command line indicating 
that an element build is desired, but the SDML file contains a <PROFILE> 
tag, indicating that a bookbuild is desired. The /PROFILE qualifier (which 


indicates an element build) should not be supplied when a bookbuild is 
desired. 


User Action: Invoke DOCUMENT without the /PROFILE qualifier. 
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QUALVALUE, at tag or text on line n of file 
file-spec 
Value string to /CONDITION qualifier is not a valid name 


Fatal: The condition name supplied with the /CONDITION qualifier must 
contain only alphabetic and numeric characters and the underscore character. 


User Action: Correct the spelling of the condition name. 


REV_PAGES, Update pages number through number will be output. 


Informational: This message indicates the pages that will be output for an 
update. 


User Action: None. 


REVISINFO, Document is using revision indicators 


Informational: This message indicates that the <REVISION> tag is being 
processed. Text that is delimited by <MARK> and <ENDMARK> tags will be 
accompanied by revision indicators on output. 


User Action: If you intend for revision bars to print in your text, you do 
not need to take any action. However, if you intended for text indicated 
by <MARK> tags to not appear in the output, you should remove the 
<REVISION> tag from the file. 


REVISTEXT, Revised pages will contain the text ‘string’. 


Informational: This message verifies the text specified in the second 
argument to the revision tag and reminds you that only pages specified 
in an update range will be processed and printed. 


User Action: None. 


REVIS_UPD, Revision will contain update pages only. 


Informational: This message reminds you that you specified 

<REVISION> (UPDATE) and that your output file will only contain the text 
for pages specified between <UPDATE_RANGE> and <ENDUPDATE_RANGE> 
tags. 


User Action: None. 


RMVCONDTN, Removing condition condition-name 
on line number of file filespec 


Informational: A <SET_CONDITION> (REMOVE) tag is being executed. 


User Action: None. 
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SAVTAGACT, at tag or text on line 7 of file 
file-spec 
Tag <tagname> has a before or after action that is 
ignored when saving a tag table 


Warning: You are attempting to invoke a tag that has a before action or an 
after action. The before action or after action cannot be executed while you 
are saving the tag in a tag table. The before action or after action will be 
executed when the saved tag table is loaded. If you receive this message and 
are under a service contract with DIGITAL, call your customer service center. 
Otherwise, submit a Software Performance Report. 


User Action: No action. However, you may want to verify that this tag 
should be invoked when the saved tag table is actually loaded. 


SAVTAGILL, at tag or text on line n of file 
file-spec 
This built-in tag cannot be invoked during the saving of a tag table 


Error: Only certain built-in tags can be stored in a saved tag table for 
invocation when the saved tag table is loaded. This tag is not one that can 
be saved. If you receive this message and are under a service contract with 
DIGITAL, call your customer service center. Otherwise, submit a Software 
Performance Report. 


User Action: Examine your need to invoke this tag when the tag table is 
loaded. If you still need to invoke the tag, store it as a quoted string in a 
string variable. Then reference the string variable. Here is an example: 


Suppose that you want to invoke the <FILE_NAME> tag during the loading 
of the saved tag table. You must store the <FILE_NAME> tag in a string and 
then output the string. 


<STRING> (my—file_name\| <FILE_NAME> &) 
<STRING> (my_—file_name) 


This works because the <STRING> tag is one of the tags that can be saved in 
the saved tag table. 


SAVTAGLEV, at tag or text on line n of file 
file-spec 
Tag <tagname> cannot be invoked within an argument list 
during saving of a tag table 


Error: During the saving of a tag table, the arguments to all tags must be 
constant or must be made constant by quoting them. If you receive this 
message and are under a service contract with DIGITAL, call your customer 
service center. Otherwise, submit a Software Performance Report. 


User Action: Place a vertical bar before the first character of the argument 
and an ampersand after the last character of the argument. 


SDML_—INFO, message 
Informational: An SDML tag is describing action taken during tag loading. 


User Action: None. The message is purely informational. 
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SECFILOPN, at tag or text on line n of file 
file-spec 
Cannot open a secondary output file named 
filename 
A secondary output file is already open. It is named 
filename 


Error: Only one secondary output file can be open at a time. If you receive 
this message and are under a service contract with DIGITAL, call your 
customer service center. Otherwise, submit a Software Performance Report. 


User Action: Use the <CLOSE_SECONDARY_OUTPUT> tag to close any 
secondary output file before using the <OPEN_SECONDARY_OUTPUT> tag 
to open a new file. 


SETCONDTN, Setting condition condition-name 
on line number of file filespec 


Informational: A <SET_CONDITION> tag is being executed or a condition is 
being set in response to a /CONDITION qualifier on the command line. 


User Action: None. 


SKIPITEMS, at tag or text on line n of file 
file-spec 
number <tagname> outside of <tagname> skipped. 


Warning: This message is usually preceded by a message indicating that an 
<LE> or <TABLE_ROW> tag was encountered; it indicates the number of 
additional. tags that were specified. The tags will not be processed, and will 

be written, unformatted, to the output file. 


User Action: Determine if the tags are considered invalid because there is no 
preceding <TABLE> or <LIST> tag, or if the <TABLE> or <LIST> tag was 
specified incorrectly. Correct your source file. 


STKOVRFLW, at tag or text on line n of file 
file-spec 
More than number nested levels of tags. (These are 
tags that are invoked inside other tags’ argument lists) 


Fatal: The tag translator limits the number of tags that can be invoked 
simultaneously. Tag B is invoked simultaneously with tag A, if it is invoked 
in the argument list to tag A. Thus, <A> (<B> (<C> )) requires that three 
tags are being invoked simultaneously. This may occur unexpectedly when 
the argument list to one of the tags is not properly terminated. 


User Action: Verify that the argument list of the tag that is specified in the 
location information has been properly terminated. 


STRFREEBA, at tag or text on line n of file 
file-spec 
Internal error. Attempt to free string with bad address 
Fatal: The tag translator’s memory allocation algorithm has failed. 


User Action: Submit a Software Performance Report. 
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STRFREE2T, at tag or text on line n of file 
file-spec 
Internal error. Attempt to free the same string twice 


Fatal: The tag translator’s memory allocation algorithm has failed. 


User Action: Submit a Software Performance Report. 


STRTOOBIG, at tag or text on line n of file 
file-spec 
Internal error. Attempting to allocate number-byte string 


Fatal: The tag translator’s memory allocation algorithm has failed. 


User Action: Submit a Software Performance Report. 


SYMFREEBA, at tag or text on line n of file 
file-spec 
Internal error. Attempt to free symbol table entry with bad address 


Fatal: The tag translator’s memory allocation algorithm has failed. 


User Action: Submit a Software Performance Report. 


SYMISSING, at tag or text on line n of file 
file-spec 
Missing symbol argument. 
Each book element must have a symbol argument 


Fatal: Each element of a book must have a unique symbol so that the element 
can be processed independently. The symbol table cannot be saved from this 
run. 


User Action: Supply a symbol as an argument to the tag. 


SYMISUSED, at tag or text on line n of file 
file-spec 
The symbol string is already in use as a symbol of type string 


Error: Each element of a book must have a unique symbol. You have 
supplied a symbol on this element of the book that conflicts with an earlier 
use of this symbol. The symbol table cannot be saved from this run. 


User Action: Correct the use of symbols on elements of the book so that each 
element has a unique symbol. If you are doing a bookbuild you must repeat 
the bookbuild in order to produce a good symbol table. If you are doing an 
element build, just correct the symbol in this tag so that this element of the 
book has a unique symbol and then repeat the element build. 


SYMNOTDEF, at tag or text on line n of file 
file-spec 
Symbol string is undefined 


Warning: A symbol has been referenced but is not in the symbol table. 


User Action: Verify that the symbol is spelled correctly and that the same 
symbol has been entered in the symbol table by the invocation of a tag that 
defines the symbol. 
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TAG_FAILS, The tag translator has detected a fatal error 


Error: The tag translator is terminating execution with failure status. The 
accompanying error message supplies details of the error. 


User Action: See the description of the accompanying error message. 


TAGFREEBA, at tag or text on line n of file 
file-spec 
Internal error. Attempt to free tag table entry with bad address 


Fatal: The tag translator’s memory allocation algorithm has failed. 


User Action: Submit a Software Performance Report. 


TAG_INARG, at tag or text on line n of file 
file-spec . 
<tagname> is invalid in an argument to <tagname> . 


Fatal: The indicated tag was specified in an argument to a tag that does not 
allow it. For example, a header level tag was specified in an argument to 
<TABLE_ROW> . 


User Action: Verify that you correctly terminated the argument list for the 
tag in which this tag was specified. 


TAGINFILE, The tag was in the file filename 


Informational: This message may accompany a message indicating that a tag 
that must be ended was not terminated. This message is output when the 
starting tag is not in the current input file. 


User Action: Use the file-spec given to determine which file contains the tag 
that was not properly terminated and terminate it. 


TAGINVALD, at tag or text on line n of file 
file-spec . 
Tag <tagname> is invalid in this context. 
The context was established by <tagname> on line number of 
filename 


Error: A tag was specified in a context where it is not valid, for example, a 
header-level tag was specified within the context of a monospaced example. 
The message tells you what tag established the context. 


User Action: Determine the current context at the point at which the message 
was issued to determine if you have forgotten a required terminator and 
correct your source file. . 


TAGINZONE, at tag or text on line n of file 
file-spec 
Tag <tagname> is invalid in the bounds of string. 


Error: A tag was specified in a context where it is not valid, for example, a 
-header-level tag was specified within the context of a monospaced example. 


User Action: Determine the current context at the point at which the message 
was issued to determine if you have forgotten a required terminator and 
correct your source file. 
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TAGNOTDEF, at tag or text on line n of file 
file-spec 
Tag <tagname> is undefined 


Warning: A tag has been invoked, but no definition exists for the tag. This 
message appears for the first invocation of an undefined tag. Subsequent 
invocations of the same undefined tag are counted, but the message is not 
repeated. A count of the total number of all invocations of undefined tags is 
reported at the end of the tag translator’s processing. 


User Action: Correct the spelling of the tag, or supply a definition for the 
tag. 


TAGNOTEND, | at tag or text on line n of file 
file-spec 
Tag <tagname> from line number not terminated 


Error: A tag that has a required terminator was not terminated. 


User Action: Locate the tag that was not terminated and include its 
terminating tag at the appropriate position in your source file. 


TAGNOTHID, at tag or text on line n of file 
file-spec 
Cannot reveal tag <tagname> . It is not hidden 


Warning: A <REVEAL_TAGS> tag is requesting that a hidden tag be revealed, 
but the tag is not currently hidden. If you receive this message and are 
under a service contract with DIGITAL, call your customer service center. 
Otherwise, submit a Software Performance Report. 


User Action: After a tag is hidden through the action of a <HIDE_TAGS> 
tag, it can only be revealed through the action of a <REVEAL_TAGS> tag. If 
the tag is given a new definition (using the <DEFINE> tag) while it is hidden, 
it will not appear to be hidden when the <REVEAL_TAGS> tag is executed, 
and this error message will occur. Check the sequence of your use of the 
<HIDE_TAGS> , <DEFINE>, and <REVEAL_TAGS> tags. 


TAGNOTPRE, at tag or text on line n of file 
file-spec 
Tag <tagname> invalid unless preceded by string 


Warn: A tag is being invoked that is invalid because it is being used out of 
context. 


User Action: Check the sequence of tags to ensure that the proper context is 
established before the tag is used. Correct the SDML source file. 


TBLATTRIB, at tag or text on line n of file 
file-spec 
Argument string to tag <tagname> is not a valid table attribute 


Warn: A keyword was specified in a <TABLE_ATTRIBUTES> tag that is not a 
valid keyword attribute for tables. 


User Action: Verify that the specified value is a valid table attribute and 
check its spelling. Correct the SDML source file. 


C-—38 


Messages 
Tag Translator Messages 


TBLATTIGN, at tag or text on line n of file 
file-spec 
<TABLE_ATTRIBUTES> specified following <TABLE_SETUP> 
ignored. 


Warning: The <TABLE_ATTRIBUTES> tag must be specified preceding the 
<TABLE_SETUP> tag. The specified attributes will be ignored. 


User Action: Move the <TABLE_ATTRIBUTES> tag in front of the <TABLE_ 
SETUP> tag. 


TBLBRKCOL, at tag or text on line n of file 
file-spec 
Table cannot be broken in column number. 


Warning: The <VALID_TABLE_ROW_BREAK> tag is valid only in columns 2 
through 4 of a table. 


User Action: Remove the <VALID_TABLE_ROW_BREAK> tag. If the text in 
the column is too long for a page, consider restructuring the table to be less 
complex. 


TBLCOLCNT, at tag or text on line n of file 
file-spec 
Tag <TABLE_SETUP> argument 1 ‘string’ is missing or is not a 
number in the range 2 through 9 


Error: The <TABLE_SETUP> tag must specify a numeric value in the range 
of 2 through 9 to specify the number of columns in the table. The indicated 
argument is invalid. 


User Action: Correct the <TABLE_SETUP> tag. 


TBLCOLNUM, | at tag or text on line n of file 


file-spec 
Table column size argument ‘string’ is missing or is not numeric 


Error: An argument specified as a width for table rows in setting up the table 
is not a numeric argument. 


User Action: Correct the <TABLE_SETUP> tag that specifies a non-numeric 
value for a table column width. 


TBLCOLWID, at tag or text on line n of file 
file-spec 
Sum of table column widths number is too large or is 0 or less. 


Error: The sum of the values specified for the column widths in the <TABLE_ 
SETUP> tag is excessive, or is less than or equal to 0. The message displays 
the current summed value of all column widths specified. 


User Action: Verify that the numbers you specified in <TABLE_SETUP> 

are accurate. Adjust them to smaller numbers so that the table will fit. If 
you did not specify <TABLE_ATTRIBUTES> (WIDE) and the document design 
you are using provides an extra margin for wide tables, specify <TABLE_ 
ATTRIBUTES> (WIDE) in front of the <TABLE_SETUP> tag. To request that the 
table appear in a smaller typesize, use <TABLE_ATTRIBUTES> (MAXIMUM). 
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TBLDUPSET, at tag or text on line n of file 
file-spec 
Tag <TABLE_SETUP> specified twice. Duplicate setup ignored. 


Warning: A table contains two <TABLE_SETUP> tags. The second tag is 
being ignored. 


User Action: Determine which <TABLE_SETUP> tag is correct and remove 
the extra one. 


TBLFNOTEM, at tag or text on line n of file 
file-spec 
Table footnote number number exceeds maximum number 


Warning: A numeric argument specified for a footnote declaration in a table 
exceeds the maximum. The maximum number of table footnotes is normally 
12; however, if you use any non-numeric keywords in table footnotes, the 
maximum number allowed is reduced to 6. 


User Action: Verify the number of footnotes in the table, and the numeric 
arguments you use to declare and reference them. 


TBLKEYDUP, at tag or text on line n of file 
file-spec 
Table already specifies <TABLE_KEY>. Duplicate ignored. 


Warning: Only one key can be specified in a table. The second key specified 
is being ignored. 


User Action: Determine which table key is the one that you want and 
remove the duplicate one. 


TBLKEYNES, at tag or text on line 1 of file 
file-spec 
<tagname> is not valid in a nested table. 
Nested table on line string in file string. 


Warning: A <TABLE_KEY> or <TABLE_KEYREF> tag was specified in a 
nested table, that is a table that is specified in another table’s <TABLE_ROW> . 
Table keys and table key references are invalid in nested tables. 


User Action: Place the table key and/or the reference to it in the outer table. 


TBLKEYNUM, at tag or text on line n of file 
file-spec 
The <TABLE_KEY> tag will replace table footnote 12. 


Warning: When a key is specified in a table, you cannot specify a table 
footnote numbered 12. The text of the table key will replace the footnote 
number 12, and references to footnote 12 will result in the table key being 
printed. 


User Action: Check the arguments you specified to the <FOOTNOTE> tags in 
the table and do not specify a number greater than 11. 
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TBLKNOREF, at tag or text on line n of file 
file-spec 
Tag <TABLE_KEYREF> tag encountered in a table that has no key. 


Warning: A <TABLE_KEYREF> tag is not valid because there is no key in the 
table to reference. 


User Action: Verify that the <TABLE_KEY> tag is correctly specified in the 
main table (it must not be specified in a nested table). If the table has no key, 
remove the <TABLE_KEY> tag. 


TBLNBREAK, at tag or text on line n of file 
file-spec 
A nested table with more than three columns cannot be broken. 


Error: The <NESTED_TABLE_BREAK> was specified in a nested table that has 
more than three columns. 


User Action: Verify that the <TABLE_SETUP> tag for the table you are trying 
to break was correctly specified. If the nested table has four columns, you 
may need to restructure your information. 


TBLNONEST, at tag or text on line n of file 
file-spec 
_ Invalid table nesting. Ignored. 


Warning: You coded a nested table incorrectly. There are three possible 
problems: 


1 You specified a <TABLE> tag with a caption argument in an argument 
to a <TABLE_ROW> tag. You cannot place a formal table inside another 
formal table. 


2 You specified a <TABLE> tag inside another table, but outside of a 
<TABLE_ROW> tag. All text (including nested tables) that occur within a 
table must be coded within <TABLE_ROW> tags. 


3 You specified <TABLE_UNIT> inside a table that is nested in another 
table. <TABLE_UNIT> tags are not valid in nested tables. 


User Action: Based on the above situations, you should take one of the 
following actions: 


1 Remove the caption argument from the nested table tag. 
2 Nest the table inside a <TABLE_ROW> tag. 
3 Remove the <TABLE_UNIT> tags. 


TBLNOROWS, _§at tag or text on line n of file 
file-spec 


A table was specified without any table rows. 


Error; <TABLE> and <ENDTABLE> tags were encountered in the file, but 
there were no <TABLE_ROW> tags between them. 


User Action: Verify that you specified <TABLE_ROW> tags correctly. Or, 
remove the <TABLE> and <ENDTABLE> tags if you did not want to place a 
table there. 


C—41 


Messages 
Tag Translator Messages 


TBLNOTDEC, at tag or text on line n of file 
file-spec 
Table footnote number is referenced but not declared. 


Warning: A <FOOTREF> tag is specified in a table, but there is no 
corresponding <FOOTNOTE> tag at the beginning of the table. The footnote 
reference will not be printed. 


User Action: Verify that you specified the <FOOTNOTE> tag correctly at the 
beginning of the table. Verify that the number specified in the declaration 
matches the number in the <FOOTREF> tag. 


TBLNOTROW, | at tag or text on line n of file 
file-spec 
Tag <tagname> specified outside of <TABLE_ROW> . 


Error: A tag is specified between two <TABLE_ROW> tags and is therefore 
not valid in this context. 


User Action: Correct your source file to move the tags and related text, if 
any, to within the bounds of a <TABLE_ROW> tag. 


TBLNOTSET, at tag or text on line x of file 
file-spec 
Table from line number has no <TABLE_SETUP> attributes. 


Error: A <TABLE_ROW> tag was encountered in a table without a <TABLE_ 
SETUP> tag. 


User Action: Correct your source file to specify the number of columns and 
widths for the table. 


TBLNOTMTP, at tag or text on line n of file 
file-spec 
<tagname> invalid in table that is not multipage 


Error: A tag, for example <TABLE_UNIT> was specified in a table that does 
not have the multipage attribute. 


User Action: Determine whether the table is a multipage table. If so, be sure 
that it is not specified with the KEEP attribute. 


TBLSPANNO, §at tag or text on line n of file 
file-spec 
Argument number to tag <SPAN> is invalid for the current 
column count. 


Warning: A <SPAN> tag’s argument exceeded the number of remaining 
columns in the table. For example, you specified <SPAN> (3) in a table with 
only 2 columns. 


User Action: Correct your source file to specify the number of columns to 
span. Be sure that your numeric argument, plus the current column number, 
do not exceed the number of columns in the table. 
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TMPNONEST, at tag or text on line n of file 
file-spec 
Invalid attempt to nest reference templates. 
Last template was string 


Error: A tag invoking a reference template was encountered when a reference 
template was already in effect; for example, a <ROUTINE_SECTION> is 
specified before a previous <COMMAND_SECTION> was terminated. 


User Action: Correct your source file to correctly terminate the reference 
section that was not terminated. 


TMPTAGDEF, You cannot redefine <tagname> using <tagname> . 


Informational: A tag that defines a template tag specified a tag name that is 
already a defined tag. This message indicates one of the following: 


¢ Your input file has more than one reference template section, and you 
used the same template tag names in both. (For example, a <SET_ 
TEMPLATE_ROUTINE> tag may specify the same tag name in more than 
one occurrence of <ROUTINE_SECTION> . 


e¢ You have specified a name that is the name of an SDML global tag. 


User Action: If the message occurred because you used the same template 
tag names in more than one reference template section, you need take no 
action. If you have used a name that is the name of an SDML tag, you 
should select another name; future use of the SDML tag name in the same 
source file may produce unpredictable results. 


TMPTAGEND, at tag or text on line 7 of file 
file-spec 
<tagname> not terminated before <tagname> . 


Warning: A tag occurring within the context of a reference template was 
not terminated before the end of the file or before the beginning of the next 
reference section. For example, an <OVERVIEW> tag from a <COMMAND> 
description was not terminated before the next <COMMAND> description was 
encountered. 


User Action: Correct the source file so that you correctly terminate the 
template tag. 


TMPTAGNAM, | at tag or text on line n of file 
file-spec 
string is an invalid template tag name. 


Error: A template tag, for example <SET_TEMPLATE_COMMAND> , specifies 
that the tag name is already defined in SDML, or it is an invalid name, that is, 
it contains more than 31 characters or it contains nonalphanumeric characters. 


User Action: Choose another name for the tag, and modify your source file. 
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UNBALPARS, at tag or text on line n of file 
file-spec 
Unbalanced parentheses in argument number 


Warning: One or more left parentheses are present without matching right 
parentheses. A sufficient number of right parentheses are appended to the 
argument to achieve a balance. 


User Action: Correct the unbalance, either by adding the proper number of 
right parentheses or by coding the left parentheses using the <OPAREN> tag. 


UNDEFSYMS, There were number undefined symbol references 


Informational: This message reports the total number of references that were 
made to undefined symbols. Only the first reference to a specific undefined 
symbol is reported. 


User Action: Either define the undefined symbol, or correct the spelling of 
the symbols being referenced. The undefined symbols were reported in other 
messages. 


UNDEFTAGS, There were number undefined tag invocations 


Informational: This message reports the total number of invocations of 
undefined tags. Only the first invocation of a specific undefined tag is 
reported. 


User Action: Either define the undefined tags, or correct the spelling of the 
tag being invoked. The undefined tags were reported in other messages. 


UPDATINFO, Update page label string, <tagname> 


Informational: A document that is being processed to produce update pages 
may have associated update information. The information indicated will be 
printed on the bottom of each page output. 


User Action: Verify that the update page label is correct for your document. 


USER_IMSG, | string 
Line is number of file filename 


Informational: This message code is used for messages written to the 
terminal or output stream when a <USER_I_MESSAGE> tag is specified in 
the input file. 


User Action: The action you take depends on the content of the user’s 
message. 


USER_WMSG, _§at tag or text on line n of file 
file-spec 
string 


Warning: This message code is used for messages written to the terminal or 
output stream when a <USER_W_MESSAGE> tag is specified in the input file. 


User Action: The action you take depends on the content of the user’s 
message. 
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USETAGDEF, Using tag’s default: number 


Informational: This informational message accompanies other warning 
messages. It generally indicates that a default value is being taken. 


User Action: Edit the SDML source file to correct the argument. 


VBARINARG, at tag or text on line n of file 
file-spec 
A vertical bar was found in argument number to tag <tagname> . 
Use the <VBAR> tag to code a vertical bar in an argument 


Fatal: The tag translator treats the vertical bar character as a special operator 
character in arguments to tags. If you include a vertical bar character in 

an argument, the tag translator may overlook the right parenthesis that 
terminates the argument list, and may scan all of the remaining input looking 
for the proper terminator. 


If you have mistakenly omitted the closing parenthesis of an argument list, 
the tag translator begins to search the remainder of your file for a closing 
parenthesis. If it encounters a vertical bar (perhaps in a figure or code 
example), it then begins to search for a matching ampersand. Thus, this error 
message may be issued instead of the EOFARGLST error message. 


User Action: Correct the argument list by replacing the vertical bar with the 
<VBAR> tag, or by properly closing the argument list. 


VMOVREFLOW, at tag or text on line n of file 
file-spec 
Internal error. Failure to allocate additional space in virtual 
memory 


Fatal: This error message is generally caused by one of two types of error in 
the SDML file. These errors, and the action that you should take to correct 
them are as follows 


e An unterminated argument list. If you fail to terminate an argument list, 
the tag translator regards the text that follows the argument list as part of 
the last argument. Suppose you write 


<EMPHASIS>(always\BOLD> press the RETURN key. 
instead of 
<EMPHASIS>(always\BOLD) press the RETURN key. 


The tag translator does not realize that the right angle bracket should 
have been a right parenthesis. It tries to include all the following words 
as part of the second argument of the <EMPHASIS> tag. This means 
that it may store large portions of the SDML file in memory while it 
searches for a closing parenthesis to the argument list. If memory limits 
are exceeded, the VMOVRFLOW error message is issued. 


¢ Too many tag definitions. The tag translator has no limit on the number 
of tag definitions. However, a limit is imposed by the memory allocation 
algorithm. When this limit is exceeded, it usually indicates that one or 
both of the following conditions are present: 


— A file that contains tag definitions is being repeatedly included. This 
file is often a global definitions file that is being used to define tags 
or symbols for text substitution. You can avoid memory limitation 
problems by using the <CHECK_FOR_INCLUSION> tag at the start of 
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such a file. This ensures that the file’s definitions are actually loaded 
only once, even though the file is included many times. 


— A tag’s definition changes frequently during execution, perhaps 
when the tag is being used to temporarily hold a text string. If the 
tag’s definition is established each time by the <DEFINE> tag rather 
than by the <REDEFINE> tag, the definitions pile up in memory. A 
reference to the tag always retrieves the latest definition, and if you 
never use the <UNDEFINE> tag to erase the latest definition, you will 
never see the old definitions, but they are still occupying memory 
space. 


User Action: Determine if the error was caused by an unclosed argument 
list. The error is generally located by the information supplied in the error 
message. 


Otherwise, examine your tag definitions to determine whether you are 
defining the same tag name multiple times. You can avoid memory limitation 
problems by defining your tags with the <REDEFINE> tag, rather than the 
<DEFINE> tag. Unless you specifically intend to “stack” tag definitions, 

and use the <UNDEFINE> tag to “pop” definitions off the stack, you should 
always establish a tag definition with the <REDEFINE> tag. 


XRFINCMPL, at tag or text on line n of file 


file-spec 
The file containing cross reference symbols is incomplete. 
filename 


Fatal: During the reading of the file containing cross reference symbols, an 
error was detected that indicates that the file was not recorded correctly. 


User Action: Submit a Software Performance Report. 


XRFINVALD, at tag or text on line n of file 


file-spec 
The file containing cross reference symbols is invalid. 
filename 


Fatal: The file was opened without error, but it does not contain cross 
reference symbols. 


User Action: The wrong file is being referenced. Check the file name 
supplied with the /PROFILE qualifier. 


XRFNORENM, | at tag or text on line n of file 


file-spec 
The temporary cross reference file cannot be renamed to 
filename 


Fatal: The tag translator creates a temporary cross reference file with a file 
type TMP. When the file is complete, it renames it with a file type XREF. The 
rename operation has failed. 


User Action: Submit a Software Performance Report. 
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C.3 Text Processor Messages 
ATPT , Font was read at number pt 
Informational: This is an internal error. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


BADALPHA , Improper alphabetic constant 
Warning: Text formatter expected to scan a constant consisting only of letters. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


BADCHAR, Text line contains an invalid character 
Warning: Text formatter could not scan a character from current input line. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


BADCODE , Bad code number: value, must be between smaller number and larger 
number 
using zero instead 


Warning: Text formatter expected to find code value within range shown. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


BADCS , Bad control sequence: ‘Command’ 


Warning: Text formatter could not understand how user meant to use the 
shown command in the current context. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


BADDISC , Improper discretionary list. Must contain only 
‘kerns’ and ‘boxes’ 


Warning: Discretionary list contained unexpected information. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 
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BADDISCMATH , Illegal “discretionary break’ in ‘math’ mode. 
The third part of a discretionary break must be empty 
in this mode. Attempting to recover... 


Warning; Discretionary break was improperly coded. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


BADDUMP, Cannot ‘\dump’ inside a group 


Warning: Command °\dump’ occurred when there was one group or more 
still active. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


BADFONTFMT , Fatal font format file error 


Error: Text formatter could not load the font format file, or the font format 
file was fatally flawed. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


BADFRACTION , Ambiguous fraction ignored. 
Warning: Text formatter could not determine the meaning of a fraction. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


BADGLUE , Infinite glue. Attempting to recover 


Warning: Text formatter was asked to typeset a box using infinite glue. Glue 
was made finite and text formatter attempted to continue. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


BADHALIGN , Improper *\halign’ 
Warning: Command ‘\halign’ was invalid in current context. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


BADHRULE , Cannot use ‘\hrule’ in an ‘\hbox’. 
Use ‘\leaders’ or ‘\hrulefill’ instead 


Warning: Command ‘\hrule’ is invalid in current context. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 
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BADHYPHEN , Improper \hypenation ignored. 
Must contain only letters and hyphens 


Warning: Text formatter can only read letters and hyphens in a hyphenation 
pattern. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


BADHYPHFMT , Fatal hyphenation format file error 


Error: Text formatter could not load the hyphenation format file, or the 
hyphenation format file was fatally flawed. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


BADLASTBOX , *\box255’ is not empty, attempting to continue 
Warning: Text formatter expected “\box255’ to be empty. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


BADLEADERS , ‘\leaders’ not followed by proper ‘glue’ 
Warning: Glue specification was not valid in current context. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


BADLETINPAT , Non-letter found in *\patterns’ 
Warning: Text formatter can only read letters in a ‘pattern’. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


BADLIMIT , Ignoring misplaced ‘\limits’ or “\nolimits’ command 


Warning: Text formatter did not expect to see ‘\limits’ or ‘\nolimits’ in this 
context. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


BADMACROFMT , Fatal macro format file error 


Error: Text formatter could not load the macro format file, or the macro 
format file was fatally flawed. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 
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BADMAG , Illegal magnification ratio: bad number, value set to good number 
Warning: Text formatter could not set magnification to requested value. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


BADMATHCHAR , ‘font’ number font-number is missing this character: ‘character’ 


Warning: Text formatter could not typeset the character shown, because that 
character was missing from the font shown. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


BADMATHDELIM , Inserted missing or misplaced math delimiter 
Warning: Text formatter became confused while closing a math formula. 


User Action: Check the SDML file for <MATH> sequences and verify that 
all parentheses are matched and that all math tags and delimiters are correctly 
terminated. If this does not correct the problem and you are under a service 
contract with Digital, call your customer service center. Otherwise, submit a 
Software Performance Report. 


BADNOALIGN , *\noalign’ can only appear after *\cr’ 
Warning: Command *\noalign’ is not valid in current context. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


BADOMIT , ‘\omit’ can only appear after “\cr’ or “&’ 
Warning: Command *\omit’ is not valid in current context. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


BADOUTLOOP, Output loop repeated number of cycles times without doing a 
‘\shipout’ 
Attempting to recover. Increase “\maxdeadcycles’ if neccesary 


Warning: Text formatter cycled through its output loop too many times 
without doing a *\shipout’. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


BADPARAMNUM , Illegal parameter number 


Warning: Text formatter became confused while scanning parameters to a 
macro. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 
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BADPARAMSEQ , Parameter was numbered out of sequence 


Warning: Text formatter became confused while scanning parameters to a 
macro because a parameter was numbered out of sequence. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


BADPATTERNS , Bad \patterns 
Warning: Text formatter became confused while reading a ‘pattern’. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


BADPREAMBLE , Cannot nest alignment preambles 


Error: Text formatter became confused during current alignment, because it 
found an alignment within an alignment. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


BADPREFIX2 , Can’t use ‘\long’ or ‘\outer’ with ‘command’ 


Warning: Text formatter will ignore ‘\long’ or ‘\outer’ or *\global’ when used 
with the shown command. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


BADPREFIX3 , Can't use ‘\long’ or ‘\outer’ or ‘\global’ with ‘command’ 


Warning: Text formatter will ignore ‘\long’ or ‘\outer’ when used with the 
shown command. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


BADPREVGRAF , ‘\prevgraf’ = number . Value must be positive 


Warning: Text formatter expected to see \prevgraf’ specified with a positive 
value. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


BADPT , Bad font size = number pt, replaced by 10 pt 
Warning: Text formatter attempted to read a font at an improper font size. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 
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BADUNBOX , Cannot ‘unbox’ a ‘hbox or vbox’ in “Text formatter mode’ mode 
Warning: command ‘unbox’ is invalid under current circumstances. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


BADUNIT , Bad unit of measure, replaced by ‘string’ 


Warning: Text formatter could not use the unit of measure user asked for. 
Unit was changed to shown value. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. . 


BADVALUE , ‘quantity’ = number . Value must be between smaller number and 
larger number 


Warning: Text formatter was expecting to read a value within the range 
shown. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


BUFFERSIZE , Maximum number of characters in the input buffer is number 
Informational: User has exceeded total size of text formatter’s input buffer. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


CANNOTRESETMAG , Cannot change magnification, using old value: number 
Warning: Text formatter can only set magnification value once. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


CONFUSION , Text formatter became confused doing this: ‘Command’ 
, job is aborting 


Error: Text formatter became confused doing the shown activity, and had to 
exit. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


CONFUSION , Text formatter became confused doing this: ‘Command’ 
, job is aborting 


Error: Text formatter became confused doing the shown activity, and had to 
exit. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 
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DIMENTOOBIG , Dimension too large 


Warning: Text formatter became confused while scanning a dimension, 
because the dimension was too big. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


DISCTOOLONG , Discretionary list is too long. Attempting to recover 
Warning: Discretionary list was too long. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


DOUBLESUB , Double subscript 


Warning: Text formatter found a quantity with two subscripts. In these cases, 
x°1°2 will be treated like x°1{}°2. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


DOUBLESUPER , Double superscript 


Warning: Text formatter found a quantity with two superscripts. In these 
cases, x_1_2 will be treated like x_1{}_2. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


DURING ,_ Error occurred during a ‘command’ 
Warning: Error occurred during a specified command or control sequence. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


DURINGOR, Error occurred during a ‘command’ or ‘command’ 


Warning: Error occurred during one of the two commands or control 
sequences shown. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


EMERGENCYSTOP , Job is aborting 
Error: Text formatter became hopelessly confused, and must exit. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 
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ENDDURING , ‘\end’ occurred during ‘command’ 
Warning: The command ‘\end’ occurred unexpectedly. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


ENDINGROUP ,, ‘\end’ occurred inside group at level number 


Warning: The command ‘\end’ occurred when there was one group or more 
still active. Examine the input and output files and attempt to determine what 
tag was not terminated. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


EOF, Unexpected end of file 


Warning: Text formatter encountered the end of the current file 
unexpectedly. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


EOP, Paragraph ended before the following completed: 
Warning: Text formatter encountered the end of a paragraph unexpectedly. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


EXTRATAB, Extra *\halign’ or *&’ in alignment has been changed to *\cr’ 
Warning: Text formatter found extra or unexpected *\halign’ or *&’. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


FILENAME , ‘file-name’ 
Informational: Identifies current file being used as input. 


User Action: This message always occurs in conjunction with other messages. 
Action depends upon associated message. 


FONTDIMEN , The following font has only number fontdimen parameters 
To increase the number of font parameters you must use 
\fontdimen immediately after the \font is loaded 


Warning: The current font has too many parameters. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 
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FONTERROR , Error occurred in the following font: 
Warning: Text formatter found an error in the current font. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


FONTMEMSIZE , Font memory size = number words 
Informational: Reports the total size of text formatter’s font memory. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


FONTTYPE , Font was declared by: ‘string’ 
Warning: Identifies the font’s type, e.g. \preloaded. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


FUNNYCS , Missing control sequence inserted 
Warning: Text formatter became confused while defining a control sequence. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. . 


IGNORED ,_ Extra ‘command’ ignored 
Warning: An unneccesary text formatting command was found. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


IGNOREDTEXT ,_ All text was ignored after line string 


Warning: Text formatter could not typeset any of the text following the line 
shown. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


IGNORING , Ignored the following: ‘command’ 


Warning: Text formatter encountered an unexpected command, and ignored 
it. 
User Action: If you receive this message and are under a service contract 


with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 
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IMPROPERCMD , Improper command found: ‘command’ 
Warning: Command shown is not valid in current context. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


INCOMPLETECMD , Incomplete command found: ‘command’ 


Warning: Text formatter became confused while trying to scan the shown 
command. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 

INFO ,_ text - on page number 


Informational: A text formatting macro has generated an informational 
message. A problem occurred while the text formatter was processing the 
output. Text provides a description of the problem. In most cases, the file 
will continue processing successfully and you can examine the output. The 
message indicates the page on which the problem occurred, and you can use 
this information to correct the problem. 


User Action: The following is a list of the messages you may see and the 
associated action that will correct the problem. 


e Callout number 0 undefined. Using 1. 
A <CALLOUT> or <CO> tag was specified as 0. 
e Callout number exceeds 99. Using 99. 


A <CALLOUT> or <CO> tag’s value is greater than 99. POSTSCRIPT 
output devices cannot print numbers greater than 99. 


e Error in setting note type; using default. 


A local or personal DESIGN file specified an invalid value for the 
\noteformattype. Refer to the VAX DOCUMENT Doctype Designer’s 
Guide for value values. 


e Error. Maximum number of table footnotes exceeded. 


Too many <FOOTNOTE> tags were specified for a table. The largest 
number that is allowed is 12. 
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Error pushing/popping revision bars. 


<MARK> and <ENDMARK> tags are not evenly matched, or are not 
suppressed around heading levels in the correct sequence. If you receive 
this message and are under a service contract with DIGITAL, call your 
customer service center. Otherwise, submit a Software Performance 
Report. 


Possible problem in output of revision bars. 


The text formatter encountered a complex situation while a revision mark 
(from the <MARK> tag) was active. Examine your output closely to 
determine if the revision mark output is correct. A revision mark may not 
appear, or appear where you did not intend it to. If there is a problem, 
you can change your source file to decrease the range in which a revision 
mark is active. For example, if you have changes in two rows of a table, 
you might place the <MARK> and <ENDMARK> tags inside each of the 
two <TABLE_ROW> tags instead of around the entire table. 


Figure is too large for a single page. 


A value specified in <FIGURE_SPACE> or <FIGURE_FILE> exceeds the 
depth of the output page. The text formatter will use only the depth of 
the page. 


Correct the invalid depth argument in the SDML file. 
<FOOTREF> before <FOOTNOTE> in table ignored. 


A tag <FOOTREF> tag occurred in a table for which no corresponding 
<FOOTNOTE> tag occured. Footnotes in tables must be specified at the 
beginning of the table, before any references to them occur. 


Graphics files cannot be included on this device. 


A <FIGURE_FILE> or <ICON_FILE> tag was encountered that specified 
a graphics file to be included on a device that does not support the 
inclusion of graphics. The tag is ignored. 


Index subentry more than 4 levels deep; ignored. 


An indexing tag (<x> or <Y>) contained more than four 
<XSUBENTRY> tags. Only four levels of subentry are allowed. 


Correct the indexing tag to remove the excessive subentries. 
Included files are not allowed to float. 


An included text formatter file in a figure is assumed to be multipage and 
cannot float. 


Remove the FLOAT attribute. 

Internal error while processing a table. 

The text formatter has received bad input. Submit an SPR. 
Invalid table of contents entry. 


A local or personal doctype specified an invalid value for a table of 
contents entry. Correct the table of contents entry to use a valid code. 


If this error occurs using a standard VAX DOCUMENT design, submit an 
SPR. 
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Monospaced example is too big to keep. 


The keyword KEEP was specified as an attribute to a <CODE_EXAMPLE> 
tag or other tag that specifies a monospaced example. The number of 
lines in the example cannot fit on a single page of output. 


Remove the keyword KEEP from the tag and provide <VALID_BREAK> 
tags to indicate acceptable page break points. 


Multipage figure will not be allowed to float. 


A figure was specified with both the attributes FLOAT and MULTIPAGE. 
Multipage figures cannot float; the text processor will output it at the 
location of its occurrence in the source file. 


Remove the FLOAT attribute. 
No template heading defined at this level; using level two. 
<PAGE> ignored in floating figure. 


A <PAGE> or <FINAL_CLEANUP> (PAGE) tag was encountered in a figure 
that had the default attribute float. 


Specify <FIGURE_ATTRIBUTES> (MULTIPAGE) for all figures that are more 
than a page in length. 


<PAGE> tag ignored in table that is not multipage. 


A <PAGE> or <FINAL_CLEANUP> (PAGE) tag was encountered in a table 
that had the default attribute float. 


Specify <TABLE_ATTRIBUTES> (MULTIPAGE) for all tables that are more 
than a page in length. 


Possible table paging problem. 


A table that is output on more than one page is being forced to break 
across pages without explicit page breaking or sufficient valid table break 
points. 


In most cases, the output will be perfectly all right. The text formatter 
makes its best decision about breaking tables across pages when there are 
<TABLE_ROW_BREAK> tags to specify the first and last valid breaks for 
the table. 


Revision bars cannot be output on this device. 


<REVISION> , <MARK>, and <ENDMARK> tags cannot be processed for 
this device. No change bars will be printed. 


<SPAN> at end of table column ignored. 


The <SPAN> tag, which specifies that text is to span 2 or more columns 
in a table, must precede the text in the argument. For example, 


<TABLE_ROW>(<SPAN>(3)This text sits across all three columns) 
Move the <SPAN> tag to the beginning of the tag’s argument. 
The table, as specified, is too wide for the page. 


The values specified in <TABLE_SETUP> result in a table that will not 
fit on the current page. Recheck the arguments you specified to the 
<TABLE_SETUP> tag, and decrease them. You will be able to tell from 
the output how much of the table is excessive. 
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®  <TABLE_HEADS> preceding <TABLE_SETUP> ignored. 


Table headings must be specified following the <TABLE_SETUP> tag. 
Move the <TABLE_HEADS> so that it precedes the <TABLE_SETUP> tag. 


e <TABLE_HEADS> within <TABLE_UNIT> ignored. 


The <TABLE_HEADS> should not be used inside <TABLE_UNIT> 
sequences; use the <TABLE_UNIT_HEADS> tag instead. 


e <TABLE_ROW> encountered outside of a <TABLE>. 


A <TABLE_ROW> tag was specified, but there was no <TABLE> tag. The 
tag will be ignored. Correct the file so that a valid <TABLE> tag precedes 
it. 


¢ <TABLE_ROW_BREAK> tags in single-page table ignored. 


The tag <TABLE_ROW_BREAK> was specified in a table that had the 
attribute KEEP specified. 


Remove the KEEP attribute from the table or remove the <TABLE_ROW_ 
BREAK> tag. 


¢ <TABLE_UNIT_HEADS> outside of table unit ignored. 


A <TABLE_UNIT_HEADS> tag was encountered before a <TABLE_UNIT> 
tag was specified to begin a table unit. 


Remove the tag; or insert a <TABLE_UNIT> tag to enclose a table unit. 
e Tracing is disabled in VAX DOCUMENT. 


An instruction to accumulate tracing information occurred in a TEX file. 
VAX DOCUMENT does not support these instructions. 


¢ Too many columns specified for multi-column output. 
A local or personal doctype specified too many columns of output. 


If this error occurs using a standard doctype, submit an SPR. 


INITEXPAT , ‘\patterns’ can only be used by Initex 


Warning: Text formatter only recognizes ‘\patterns’ when it is building 
format files, not during a run of VAX DOCUMENT. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


INSERTED , Missing ‘command’ inserted 
Warning: A missing command was inserted into input stream. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 
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INSERTHBOX , ‘\insert’ can only be added to a ‘\vbox’ 
Warning: command ‘\insert’ is not valid in current context. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


INSERTING , Inserting ‘command’ 


Warning: Text formatter attempted to resolve an unexpected situation by 
inserting shown command into input stream. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


INSUFEXTFON , Math formula deleted: Insufficient ‘extension’ fonts 


Warning: Math formula could not be typeset because ‘extension’ fonts were 
inadequate or missing. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


INSUFSYMFON , Math formula deleted: Insufficient ‘symbol’ fonts 


Warning: Math formula could not be typeset because ‘symbol’ fonts were 
inadequate or missing. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


INTERNALERROR , Internal error number: “error number’. Job is aborting 
Error: Text formatter found an internal inconsistency. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


LINE, Error occurred on or around line number: number 


Informational: Reports the current line of input that the text formatter is 
processing. 


User Action: This message always occurs in conjuction with other messages. 
Action depends upon associated message. 


LINETOOLONG , Line too long by Integer.remainder points 
Informational: The text formatter found an overly lengthy line. 


User Action: This message always occurs in conjuction with other messages. 
Action depends upon associated message. 
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LINETOOSHORT , Line too short - on page Page number 
Informational: The text formatter found a line that was too short. 


User Action: This message always occurs in conjuction with other messages. 
Action depends upon associated message. 


MATHOVERFLOW , Arithmetic overflow 
Warning: The result of a mathematical operation was too large. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


MAXFONTS , Maximum number of fonts is: number 
Informational: User has exceeded maximum number of fonts. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


MAXGROUPS , Maximum number of groups is: number 
Informational: User has exceeded maximum number of groups. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


MAXHASH , Maximum number of entries in hash table is: number 


Informational: User has exceeded maximum number of entries on text 
formatter’s hash table. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


MAXHYPHS , Number of hyphenation exceptions is: number 
Informational: User has exceeded maximum number of hyphenations. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


MAXINPUTS , Maximum number of simultaneous input files is: number 


Informational: User has exceeded maximum number of simultaneous input 
files. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 
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MAXNESTS , Maximum number of simultaneous semantic levels is number 


Informational: User has exceeded maximum number of simultaneous 
semantic levels in text formatter. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


MAXPARAMS , Maximum number of simultaneous text macro parameters is 
number 


Informational: User has exceeded maximum number of parameters to a 
macro. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


MAXSAVE , Maximum number of entries on save stack is: number 


Informational: User has exceeded maximum number of entries on text 
formatter’s save stack. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


MAXSTRINGS , Maximum number of strings is: number 
Informational: User has exceeded maximum number of strings. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


MEMORYSIZE , Main memory size = number words 
Informational: User has exceeded total size of text formatter’s main memory. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


MESSAGE , _ text - on page number 


Warning: A text formatter macro generated a warning message. The 
following is a list of possible messages and actions. 


User Action: See the action associated with each of the following messages. 
e Error in window size. 


An error occurred in a local or personal doctype; an invalid value was 
specified in a \window. 


If this error occurs in a standard doctype, submit an SPR. 
¢ Internal error in setting block indents. 


Too many arguments were specified to \blockindents, or the values were 
not valid. This error should only occur if a local or personal DESIGN file 
contains an invalid value. 


C-—62 


Messages 
Text Processor Messages 


e Internal error in figure key definition. 
Submit an SPR. 
e Too many floating figures. 


There are too many <FIGURE> tag sequences within a short span of text 
specified, and the default attribute “float” is in effect for all of them. 


The text formatter cannot produce meaningful output when there are too 
many figures that are floating. When you have a large number of figures 
in a short span of text, you should use the <FIGURE_ATTRIBUTES> (KEEP) 
tag to keep them in sequential order. 


¢ No room for a new [item]. 


Internal use. 


MISSINGBOOL , * <’ or =’ or *>’ 
Warning: Text formatter expected to scan one of the Boolean values shown. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. Determine which Boolean value is needed 
and insert it in the right place. 


MISSINGLBRACE , Possible missing *{’ 
Warning: Text formatter did not see an ‘{’. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


MISSINGRBRACE , Possible missing ~}’ 
Warning: Text formatter did not see an °)’. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


MODE, Error occurred in ‘string’ mode’ 
Informational: Reports the current mode that the text formatter is in. 


User Action: This message always occurs in conjunction with other messages. 
Action depends upon associated message. 


MUERROR , Mismatched glue units. Assuming that 1mu=1pt 
Warning: Text formatter scanned glue specifications that are incompatible. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 
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NOBOX , Expected to find ‘\hbox’ or “\vbox’ or 
‘\copy’ or \\box’ or something like that. 
Some text may be missing from output. 


Warning: Text formatter expected to find a box. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


NOEND, No ‘\end’ was found 
Error: Text formatter expected to see a ‘\\end’ command. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


NOFONTID , Could not find font identifier for the following font: 
Warning: Font identifier for current font is missing. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


NOINSLASTBOX ,_ *\insert255’ is illegal. Changing to ‘\insert0’ 


Warning: Text formatter register “\insert255’ cannot be used in current 
context. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


NOMATHACCENT ,_ Changed *\accent’ to ‘\mathaccent’ 


Warning: The text formatter command *\accent’ works differently in formulas 
than it does in normal text. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


NONUMBER, Missing number, using zero 
Warning: Text formatter expected to find a number. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


NOROOM , Exceeded memory capacity: 


Error: Text formatter exceeded one of its memory capacities. The message 
immediately following indicates which quantity was exceeded. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 
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NOUSEAFTER , After this: “command.’, the following is invalid: 


Warning: Text formatter cannot use the command shown in the next message 
directly after the command shown in this message. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


NUMBERTOOBIG , Number too large, using 2147483647 instead 


Warning: Text formatter could not use specified number because it is too big. 
Text formatter used 2147483647 instead, which is the largest number possible 
in that context. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


ONEOFFOUR , Some or all of the following 4 messages apply: 


Warning: One or more of the four messages that follow on your screen 
apply. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


ONEOFTWO , One or both of the following messages apply: 
Warning: One or both of the two messages that follow on your screen apply. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


ONPAGE , on page number 
Informational: Identifies the current page being output. 


User Action: This message always occurs in conjunction with other messages. 
Action depends upon associated message. 


OUTFILENAME , ‘file-name’ 
Informational: Identifies the output file name. 


User Action: None. 


PAGESOUT , number page(s) written. 
Informational: Reports the number of pages written to the output file. 


User Action: None. 


PAGETOOBIG , Cannot ship out huge page. More than 18 feet wide or long. 


Warning: Text formatter became confused during typesetting of current page 
because page was too large. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 
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PAGETOOLONG , Page too long by string.string points 


Warning: Text formatter could not fit contents of current page into 
boundaries of current page. Such errors are common with a line printer 
because it is monospaced. 


User Action: Examine output on page shown to determine if there is a 
problem with the coding of the SDML file. Ignore the problem if it is not 
serious. You also have the options of changing destinations or changing the 
doctype, if possible. 


PAGETOOSHORT , Page too short - on page Page number 


Informational: The text formatter had trouble composing the current page. 
There were not enough lines to reach the bottom. Such errors are common 
with a line printer because it is monospaced. 


User Action: Examine output on page shown to determine if there is a 
problem with the coding of the SDML file. Ignore the problem if it is not 
serious. You also have the options of changing destinations or changing the 
doctype, if possible. 


PATTERNEXISTS , Duplicate ‘pattern’ found 
Warning: Text formatter found a duplicate ‘pattern’. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


PATTERNMEMSIZE , Hyphenation pattern memory size = number words 


Informational: User has exceeded total size of text formatter’s hyphenation 
memory. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


POOLSIZE , String memory size = number bytes 
Informational: User has exceeded total size of text formatter’s string memory. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


RUNAWAY , Runaway “kind of text’ 


Warning: Text formatter became confused while scanning the shown kind of 
text. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 
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SCALED , Font was scaled: number 
Informational: This is an internal error. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


SHOWCONTEXT , ‘text’ 


Informational: Displays input stream that the text formatter was attempting 
to read when something went wrong. 


User Action: This message always occurs in conjunction with other messages. 
Action depends upon associated message. 


SHOWTOKEN , ‘text’ 
Informational: Displays part of text formatter’s current token list. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


TIGHTSPACING , Insufficient inter-word spacing - on page Page number 


Informational: The text formatter had trouble composing a line - there was 
not enough white space on the line. Such errors are common with a line 
printer because it is monospaced. 


User Action: Examine output on page shown to determine if there is a 
problem with the coding of the SDML file. Ignore the problem if it is not 
serious, You also have the options of changing destinations or changing the 
doctype, if possible. 


TOOFEWLINES , Excess inter-line spacing - on page Page number 


Informational: The text formatter had trouble composing the current page. 
There was too much white space between the lines. Such errors are common 
with a line printer because it is monospaced. 


User Action: Examine output on page shown to determine if there is a 
problem with the coding of the SDML file. Ignore the problem if it is not 
serious. You also have the options of changing destinations or changing the 
doctype, if possible. 


TOOMANYERRORS ,_ Error limit is 30 
Error: Text formatter found more than 30 errors. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


Messages 
Text Processor Messages 


TOOMANYILINES , Insufficient inter-word spacing - on page Page number 


Informational: The text formatter had trouble composing the current page. 
There was not enough white space between the lines. Such errors are 
common with a line printer because it is monospaced. 


User Action: Examine output on page shown to determine if there is a 
problem with the coding of the SDML file. Ignore the problem if it is not 
serious. You also have the options of changing destinations or changing the 
doctype, if possible. | 


TOOMANYPARAMS , More than nine parameters were passed to a macro 


Warning: Text formatter became confused while scanning parameters to a 
macro because there were too many parameters. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


TRACE ,_ text 


Informational: User has turned on text formatter’s tracing mechanism. Text 
contains information about VAX DOCUMENT’s text formatter’s internals. 


User Action: None. 


UNDEFINEDCS , Undefined control sequence 
Warning: Text formatter encountered an undefined control sequence. 


User Action: This can happen if a TEX file, created using one doctype, is 
reprocessed using another doctype; for example, if you created a TEX file 
using the LETTER doctype then reprocessed the file using /NOTAG and the 
OVERHEADS doctype. Reprocess the file using /TAG_TRANSLATORT and 
/TEXT_FORMATTER. If you receive this message and are under a service 
contract with DIGITAL, call your customer service center. Otherwise, submit 
a Software Performance Report. 


UNKNOWNUNIT, Dimension unit must be: em,ex,in,pt,pc,cm,mm,dd,cc,bp,sp 
Warning: Text formatter expected to read one of the dimensions shown. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


USINGZERO , Bad ‘value’, must be between smaller number and larger number, 
using zero instead 


Warning: Text formatter expected to scan a value in the range shown. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 
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VSPLITHBOX , Attempted to *\vsplit’ a “\hbox’ 
Warning: Command *\vsplit’ is not valid in current context. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


WIDESPACING , Excess inter-word spacing - on page Page number 


Informational: The text formatter had trouble composing a line; there was 
too much white space on the line. Such errors are common with a line printer 
because it is monospaced. 


User Action: Examine output on page shown to determine if there is a 
problem with the coding of the SDML file. Ignore the problem if it is not 
serious. You also have the options of changing destinations or changing the 
doctype, if possible. 
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BADFILABORT , file bad—aborting run 


Error: The device converter cannot use the font file named in an adjacent 
message. 


User Action: Another file may have been given the same name. Use the 
DIRECTORY/FULL DCL command to see that the size and format are similar 
to other font files. If necessary, reinstall the font data. 

BADFONT , font file bad—using blanks 


Warning: The file that describes the font design is unusable. The program 
will substitute blanks for the characters in this font. 


User Action: Use the DIRECTORY/FULL DCL command to see if the size 
and format of this file resembles other font files. If necessary, reinstall the 
font data. 


BADINCLUDE , included file is bad 


Warning: The program has encountered errors in processing the contents or 
index file requested. 


User Action: Check that previous processing steps generated the contents or 
index file expected; this may be an old, incompatible file, it may be another 
file with the same name, or it may be the correct file made unreadable 
because of an I/O error. 


BADMETRIC ,_ bad metric file 


Error: The device converter has encountered errors in processing the 
indicated font metric file. 


User Action: This may be another file named the same; check the file size 
and format with the DIRECTORY/FULL DCL command to see if it resembles 
other font metric files. It may be necessary to reinstall the font data. 


CANNOTCONNECT , cannot connect along a diagonal 


Warning: While attempting to draw change bars, the program has 
encountered an attempt to draw a non-vertical line. Only vertical change 
bars are allowed. 


User Action: This is controlled by the macros that describe change bar 
positioning. Look there for errors and inconsistencies. 


CANNOTCREATE , cannot create output file 
Error: The program cannot create an output file. 


User Action: Check that the output directory exists, that the user has 
permission to write in it, and that the device is available and is not full. 


CANNOTOPEN , cannot open input file 
Error: The program cannot open the input DVI file. 


User Action: Check that the input directory exists; check that the file exists 
or was created by earlier processing steps; check that the user has permission 
to read the file, and that the device is available. 
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CONFIGERROR , error in configuration file 


Error: An error has been detected in reading the file that describes 
POSTSCRIPT fonts. An adjacent error message gives more details. 


User Action: Check that the device is available and that the user has 
permission to read the file. Take the action suggested by the adjacent error 
message. If necessary, reinstall the font data. 


FILENESTING , one included file cannot include another file 
Warning: One contents or index file may not include another. 


User Action: Check the macros that describe contents and index files to see 
that they are correctly generating the filespecs; see if the filespec generated 
for the contents or index file is the same as an existing file. 


FONTCONFIG , font description missing or illegal in configuration file 


Error: The specified font is not present, or not fully described, in the file that 
describes POSTSCRIPT fonts. 


User Action: If necessary, reinstall the POSTSCRIPT support. 


FONTERROR , error in font 
string 


Warning: An error has occurred while processing the named font. The 
specific problem is identified in an adjacent message. 


User Action: Note the name of the font. Take the action suggested by the 
adjacent error message. 


FONTTOOBIG , too many characters in font—limit is 188 
Error: The document uses too many characters from the named font. 


User Action: Reinstall the font files. If problem persists, and if you are 
under a service contract with DIGITAL, call your customer service center. 
Otherwise, submit a software performance report (SPR). 


IGNORING , ignoring included input file 
filespec 


Warning: The program cannot process the included DVI file for the reason 
specified in an adjacent message. 


User Action: Note the name of the file. Take the action suggested by the 
adjacent error message. 


INCLUDING , including input file: 
filespec 


Informational: Reports that the program is processing a DVI file other than 
the file named on the command line; this is typically a contents or index file. 


User Action: None. 
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INPUTBAD , bad input file—aborting run 


Error: The program has encountered errors in the named input file and 
cannot continue. 


User Action: Check the messages generated by earlier processing steps to see 
if a complete DVI file was created. 


INPUTFILE , input file is: 
filespec 


Informational: Reports the name of the primary DVI file; i.e., the file named 
on the command line. 


User Action: None. 


INTERNALERROR , internal error 
Error: A problem internal to the device converter prevents it from continuing. 


User Action: This sometimes represents a document so large or complex 
that it exceeds internal buffer sizes; sometimes you can work around this by 
running contents and index processing as separate jobs, rather than including 
them in place. You may be able to process the document in two or more 
pieces by using the STARTING_PAGE and ENDING-PAGE or NUMBER 
OF_PAGES parameters to the device converter. If you receive this message 
and are under a service contract with DIGITAL, call your customer service 
center. Otherwise, submit a Software Performance Report. 


INVALIDPOINT , invalid point number ‘number’ 


Warning: An error has occurred in the macros used to describe change bars. 
Specifically, an attempt has been made to locate a point off the page, or the 
point is incorrectly described. 


User Action: This is controlled by the macros that describe change bar 
positioning. Look there for errors and inconsistencies. 


NOFILABORT , cannot open file—aborting run 
Error: The device converter cannot open the named file. 


User Action: Check to see that the device is available, that the file exists, and 
that the user has privileges to access that file. 


NOFONT , cannot open font file—using blanks 
Warning: The device converter cannot open the named font file. 


User Action: Check that the device exists and is available, and that the user 
has permission to read the file. 


NOINCLUDE , cannot open included file 


Warning: The device converter cannot open the contents or index file named 
in the adjacent message. Either the pathname and filename are incorrect, 

or the program cannot gain access because of file protection or locking by 
another process. Processing will continue without this file. 


User Action: Check that the named file exists and that the user has access to 
it. 
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NOINPUTPAGE , no pages in input file 


Error: The input file named in an adjacent message contains no pages; 
therefore, there will be no output to print. 


User Action: Check to see if errors reported in earlier processes caused there 
to be no pages generated. 
NOMETRIC , cannot open metric file 


Error: The font metric file named in an adjacent message does not exist, or 
the user does not have access to it because of file protection or problems with 
the device. 


User Action: Check that the file exists and is available, and that the user has 
access to it. Check that the user is specifying a DVI input file appropriate for 
the destination requested. 

NOSIXELIMAGE , cannot find sixel image in figure file 


Warning: The figure file named in an adjacent message does not contain the 
command sequence that identifies a sixel image. White space appears where 
the figure is expected. 


User Action: Check the figure file. For LN03 use, it must be a sixel file. 


NOSUBSTITUTE , no adequate alternate font found 


Error: The text formatter has requested a down-loaded font for which the 
device converter cannot find a reasonable substitute. 


User Action: Check the document design for the fonts used; check that the 
corresponding font files exist at the sizes desired. 
NOSUCHUNIT, no such unit of measure 


Warning: A DVI special command used to position change bars or describe 
graphics files contains an unknown unit of measure, or no unit at all. 


User Action: This is controlled by the macros that describe change bar 
positioning or figure file characteristics. Look there for errors. 
OFFPAGE , cannot set text outside page boundaries 


Warning: An attempt has been made to set text outside the boundaries of the 
physical page specified. 


User Action: Check the messages from the text formatter for lines too long; 
check that you specified a destination that can print a page as large as 
required by your design; check to see if you specified a horizontal or vertical 
offset that will push your design off the page. 


ONPAGE , on page [string] 
Informational: Reports the number of the output page on which the 


condition reported in the associated messages occurred. 


User Action: Note this page number if you need to refer to the output. 
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OUTPUTFAIL, error writing to output file 


Error: The program encountered an error in writing to the output file. This 
usually means that the output disk is full, the user’s disk quota is exceeded, 
or the output disk has become unusable. 


User Action: Check that the output device is usable. If the disk is full or 
the user’s disk quota is used up, delete unwanted files and run the device 
converter again. 


PAGENOTFOUND , starting page not found 


Error: The user has specified a starting page number, but that page does not 
exist in the input file. 


User Action: Check the starting page specified; check the input file specified. 


PAGESOUT , number page(s) written to file: 
filespec 


Informational: This reports the number of pages written to the output file 
named. 


User Action: No direct action needed; however, if the number is zero, or less 
than expected, check other messages for errors or examine the commands, 
filespecs, options, and input files for problems. 


PAGETOOCOMPLEX , cannot hold all font data—using blanks 


Warning: The amount of font data required to describe all the characters 
on this page will not fit in the LN03 font memory, so the characters in the 
current font will be represented as blanks. 


User Action: If using a design that allows you to change text_size, choose 
a smaller size; or use only one kind of emphasis on the page if possible; or 
move portions of the text to adjacent pages. 


PLOTFILEFAIL , cannot open figure file 


Warning: The program cannot find the figure file named, or can find it but 
cannot open it. 


User Action: Check that you have specified the right filespec, that the 

file exists in the path specified (or current default directory, if no path is 
specified), that you have permission to read that file, and that the file is not 
locked by the action of some other program running at the same time. 


PROLOGERROR , error in prolog file 


Error: The device converter cannot read its file that contains the POSTSCRIPT 
prolog for output. 


User Action: Check that the device is available, that the file exists, and that 
the user has privileges to access the file. If necessary, reinstall the POSTSCRIPT 
support. 
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SPECIALERROR , error in \special 
string 


Warning: This lists the text of a DVI special command as received by the 
device converter. This command is generated by macros, but may contain 
some user-specified information, such as a filespec or size. The specific 
problem associated with this special will be described in an adjacent message. 


User Action: Consult the adjacent message for a description of the problem. 
If necessary, check this message for a filespec or size that may have been 
incorrectly entered in a tag describing a figure file, contents file, or index file. 


SPECTOOLONG , \special too long—will try to process anyway 


Warning: This DVI special command exceeds the maximum length of 1000 
characters. The program will truncate the command and try to process it. 


User Action: Check the macros that generate this special command— 
they may be appending too many spaces or extraneous text following the 
command. 


TOOMANYDVI, too many included input files 
Warning: Too many included contents or index files have been requested. 
User Action: Remove excess contents_file and index_file tags from input 
file. 

TOOMANYFONTS , too many fonts—limit is 100 
Error: The document contains too many fonts. 


User Action: Change the document design so it does not require so many 
fonts, or use SDML tags that do not require so many fonts, or break 

the document into separate documents, or process the contents or index 
separately. 


TOOMANYGLYPHS , too many glyphs used in all fonts combined 


Error: The document contains too many characters in too many fonts. The 
LNO3 cannot hold this many characters. 


User Action: Break the device conversion of this document into two or more 
jobs, specifying the starting page and ending page or number of pages. End 
one job before the page on which this error was reported. 


UNRECOGOPTN , unrecognized option 


Warning: This DVI special command contains an option not supported by 
this device converter, or the program cannot find an option at all. 


User Action: Check to see if you have requested a figure file, contents 
file, index file, change bars, or other function which is not supported for 
this destination; check for errors in the macros that generate this special 
command. 
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ARGLST_TOO_LONG , The argument list is too long, or is not terminated. 
Error: An error occurred when the indexer read your INX file. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


ATRLST_INVALID , The attribute list is not validly constructed. 
Error: An error occurred when the indexer read your INX file. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


BADLOGIC , internal logic error detected 
Error: The INDEX utility has detected an internal failure. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


BADVALUE , ‘string’ is an invalid keyword value 
Error: The indicated string is not a valid keyword value. 


User Action: Reprocess the input file specifying a correct value for the 
qualifier keyword. 


BEGIN_QUOTE , Needs a” character or a * character to begin string. 
Error: An error occurred when the indexer read your INX file. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


CANT_CREATE_BRN , Can’t create intermediate file 
Error: A necessary intermediate file cannot be created. 


User Action: Check to be sure your INX file has not been corrupted, that 
you have sufficient disk space, that you have access to the current directory, 
and that there are no other factors in your current environment that would 
prevent the creation of a file during processing. 


CREATED , ‘string’ created 
Success: The indicated output file has been created. 


User Action: None. 


CUT_PAGE-PREFIX , Page prefix was truncated to string. 
Warning: A page prefix is greater then eight characters. 


User Action: If truncation is not accepted, change the prefix to eight 
characters or less in the INX file and resubmit. 
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DUPBEGIN , duplicate BEGIN attribute ignored. 
Warning: A BEGIN was encountered within the scope of another BEGIN. 


User Action: Check the index entries in your source file to be sure that 
BEGIN’s and END’s match. 


EMPTYIN , empty intermediate input file. 
Warning: The intermediate work file is empty. 


User Action: Check the command line to be sure that the input file was 
spelled correctly. 


ENDPASS_1, End of first pass over input file: 
‘filename’ 


Informational: Indicates that the INDEX utility has started processing the 
specified input file. 


User Action: None. 
ENDPASS_2, End of second pass over the input. 
Success: The indexing utility has completed processing the input file. 


User Action: None. 


END_—QUOTE_1, Needs a’ character to end string. 
Error: An error occurred when the indexer read your INX file. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


END_QUOTE_2, Needs a” character to end string. 
Error: An error occurred when the indexer read your INX file. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


IGNORED , ‘string’ ignored 


Warning: The indicated command line qualifier or qualifier keyword was 
ignored. One or more messages follow to indicate the reason. 


User Action: See the explanation in the error messages that follow on your 
screen. 


INPUT_OVERFLOW , Overflowed input put-back stack; element too large. 
Error: An error occurred when the indexer read your INX file. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 
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INSVIRMEM , insufficient virtual memory 


Error: The INDEX utility does not have sufficient virtual memory to generate 
the index. 


User Action: Either reduce the size of the index or increase the SYSGEN 
parameter, VIRTUALPAGECNT, reboot, and reprocess your file. 


INVINPUT , invalid input file format for intermediate file. 


Warning: The intermediate input file is not compatible with the INDEX 
utility. It may have been corrupted. 


User Action: Reprocess to get a new file. 


INVRECORD , invalid record type in intermediate file. 


Warning: The intermediate input file is not compatible with the INDEX 
utility. It may have been corrupted. 


User Action: Reprocess to get a new file. 


LANG_IGNORED , LANGUAGE tag not at beginning of file - being ignored. 


Warning: The language tag was encountered in the INX file after index entry 
processing has started. 


User Action: Reposition the language tag to the start of the INX file. 


LANG—NAME , The string language name is not valid. 
Fatal: The language specified is not supported. 


User Action: Modify the language tag in the INX file to specify Danish, 
English, Finnish, French, German, Italian, Norwegian, Portuguese, Spanish, 
or Swedish. 


NEEDS_START , Needs a = character in front of the string. 
Error: An error occurred when the indexer read your INX file. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


NOBEGIN , END attribute ignored; no corresponding BEGIN. 


Warning: An END was encountered and no previous BEGIN was 
encountered. 


User Action: Check the index entries in your source file to be sure BEGIN’s 
and END’s match. 


NOBRN , error converting ‘string’ to internal file 


Error: The indicated input file was not converted to an internal index 
workfile. 


User Action: Correct any problems noted by the file conversion routine. 
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NOEND , BEGIN has no corresponding END 
Warning: A BEGIN was encountered and the matching END was not. 


User Action: Check the index entries in your source file to be sure BEGIN’s 
and END’s match. 


NOINDEX , no index information in intermediate file. 
Warning: No index information was found in the intermediate work file. 


User Action: Check your input file to see if it includes any index entries. 


NOLIST , parameter list not allowed 


Warning: More than one file was specified on a line of a master index options 
file. 


User Action: Modify the options file so that it contains only one name on 
each line. 


NOREF , page reference not found 
Error: An internal logic error was detected. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


NOT_UNDELIM_STR, Not an undelimited string. 
Error: An error occurred when the indexer read your INX file. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


NO_ARGLST , string tag not followed by a starting argumentlist. 
Error: An error occurred when the indexer read your INX file. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


NO_ENTRY_BLOCK , Attribute build failure - no entry block built. 
Error: An error occurred when the indexer read your INX file. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


OPENIN , error opening ‘filename’ for input 


Error: The input file is erroneous, the file does not exist, or you do not have 
access to the file. 


User Action: Check the file specification for errors and check to see if you 
have access to the file. 
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OPENOUT , error opening ‘string’ for output 


Error: An output file cannot be opened. This message is usually accompanied 
by a VAX RMS message indicating the reason for the failure. 


User Action: Take corrective action based on the associated message. 


PAGE_NUMBER , Illegal page number. 
Error: An error occurred when the indexer read your INX file. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


SECTION—NAME , The string section name is not valid. 
Error: The indicated section name is not CHAPTER, PREFIX or APPENDIX. 


User Action: Change the section name in the INX file and resubmit. 


SKIPPED , n reference(s) inside page range - ignored 


Warning: The INDEX utility detected n index entries inside a BEGIN/END 
page range. These entries were ignored. 


User Action: Check the input file to be sure that the BEGIN and END are 
positioned properly. If so, remove the intervening index entries. 


SYNTAX, error parsing ‘string’ 


Warning: The indicated string encountered during the processing of a master 
index options file is erroneous. One or more messages follow indicating the 
nature of the error. 


User Action: See the description in the messages that follow on your screen. 


TEXT , string 


Informational: This message follows other error messages that are generated 
when an error in a master index file or text processor character file is detected. 
It shows the full line of the options file that was in error. It is accompanied 
by one or more other error messages. 


User Action: See the action for the accompanying error messages on your 
screen. 


TEXTD , entry text: ‘string’ 


Informational: This message follows other messages generated due to some 
error in an index entry. It shows the complete text of the index entry. 


User Action: See the action for the accompanying error messages on your 
screen. 


TOKEN—OVERFLOW , A token is more than string characters long. 
Error: A control string is more than the indicated length. 


User Action: Check the item reported and modify the INX file for proper 
format. 


Messages 


TOODEEP , maximum subindex depth exceeded 


Warning: An index entry containing ten or more levels of subindexing was 
detected. The subindexing was ignored. 


User Action: Generate index entries with fewer levels of subindexing. 


TRUNCATED , string too long - truncated 


Warning: A character string is too large to fit into an INDEX utility internal 
buffer. 


User Action: If you receive this message and are under a service contract 
with DIGITAL, call your customer service center. Otherwise, submit a 
Software Performance Report. 


VALERR , specified value is out of legal range 
Error: This message is part of a compound message. 


User Action: Look at the associated messages for an indication of what is out 
of range. 


WHERE , in string tag on line number of the INX file. 
Informational: Locates the error. 


User Action: See the action for the accompanying error messages on your 
screen. 


WHERE , in string tag on line number of the INX file. 


Informational: Locates the error. 


User Action: See the action for the accompanying error messages on your 
screen. 
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Table D-1 provides an alphabetic list of the tags that VAX DOCUMENT 
recognizes. For each tag, the doctype is given. The doctype is shown in the 
table as Global or as one of the doctypes. 


If the doctype is specified as Global, the tag is recognized in all doctypes.' 
Global tags are described in VAX DOCUMENT User Manual, Volume 1. 


If the doctype listed is one of the standard doctypes, the tag is recognized 
only for that doctype and is described in VAX DOCUMENT User Manual, 
Volume 2. 


-Table D-—1 Summary of VAX DOCUMENT Tags 





Tag Doctype Description 

<ABSTRACT> - ARTICLE Creates an article abstract and can also specify a 
heading for that abstract. 

<ABSTRACT> Global Begins a summary description of a document on 
the title page or part page of a document. 

<ACCENT> Global Supplies a freestanding accent mark. 

<ACKNOWLEDGMENTS> ARTICLE Creates an acknowledgments section in an article. 

<ALIGN_AFTER> Global Allows you to position formatted text in a list. 

< ALIGN _CHAR> Global Identifies a nonprinting character to be used to 
align numeric information within a column of a list 
or table. 

<ALIGN_NUMBER> Global Specifies a numeric value with alignment 
characters. 

<AMPERSAND> Global Supplies an ampersand within an argument to a 
tag or in math. 

<APPENDIX> Global Begins an appendix. 

<ARGDEF> SOFTWARE Begins the text that defines an item in an 
argument definition list. 

<ARGDEFLIST > SOFTWARE Begins a definition list describing zero or more 
routine arguments. 

<ARGITEM> SOFTWARE Labels one to seven routine argument items to be 


defined in an argument definition list outside of 
the Routine template, or a single routine argument 
and its attributes within the Routine template. 


<ARGTEXT> SOFTWARE Labels definition text in an argument definition list 
which replaces the information contained in a pair 
of <ARGITEM> and <ARGDEF> tags. 


<ARGUMENT > SOFTWARE Emphasizes an argument name within text. 
<AUTHOR> ARTICLE Specifies an author of an article. 


1 A few exceptions to this rule are noted in the introductions to the doctypes in VAX DOCUMENT User Manual, Volume 2. 
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Tag 
<AUTHOR> 


<AUTHOR> 


<AUTHOR_ADDR> 


<AUTHOR_AFF> 


<AUTHOR_INFO> 


<AUTHOR_LIST> 


<AUTO_NUMBER> 


<BACKSLASH> 
<BACK_NOTE> 


<BACK_NOTES> 
<BIBLIOGRAPHY > 
<BIB_ENTRY> 
<BOX> 


<BYLINE> 
<BYLINE> 
<CALLOUT > 


<CALLOUTS> 


<CALLOUT_REF> 
<CC> 


<CCLIST > 


<CENTER_LINE> 


Doctype 
REPORT 


SOFTWARE 


ARTICLE 


ARTICLE 


OVERHEADS 


ARTICLE 


OVERHEADS 


Global 
ARTICLE 


ARTICLE 
ARTICLE 
ARTICLE 
Global 


REPORT 


SOFTWARE 


Global 


Global 


Global 
LETTER 


LETTER 


Global 


Description 


Places the name of an author and one or two 
additional lines of information about the author in 
the front matter portion of a document. 


Places the name of an author and one or two 
additional lines of information about the author in 
the front matter portion of a document. 


Specifies the address of the author. 


Specifies information about the organizational 
affiliation of the author. 


Specifies informational text about the overhead 
presentation. 


Creates a list of authors for an article with 
multiple authors. 


Specifies that slides are to be numbered 
automatically, and that the slide number is to be 
placed at the bottom of every slide. Optionally, 
specifies a text string to be placed in front of the 
slide number on each page. 


Supplies a backslash within an argument to a tag. 


Creates a back note entry, and creates a 
superscript reference number in the article text. 


Causes any accumulated back notes to be output. 
Begins a bibliography. 
Specifies a single entry in a bibliography. 


Produces a box that surrounds a user-specified 
character string. 


Places a name and other optional information 
below a ruled line in a signature list. 


Places a name and other optional information 
below a ruled line in a signature list. 


Labels a callout in an example. The <CALLOUT> 
tag is identical to the <CO> tag. 


Labels the beginning of a series of callouts 
contained in an example and enables the use 
of the <CALLOUT> and <CO> tags. (The 
<CALLOUT> tag is equivalent to the <CO> 
tag.) 

Labels a reference to a callout in text. 


Lists the name of someone who is to receive a 
copy of a memo or letter. 


Begins a list of persons to whom you want to 
send a copy of a memo or letter. 


Specifies a line of text that is to be centered in 
the current text margin. 
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Tag Doctype Description 

<CHAPTER> Global Begins a chapter. 

<CHEAD> Global Marks an unnumbered centered heading. Similar 
to the <CENTER> tag. 

<CHEAD> LETTER Creates a centered heading. 

<CHEAD> REPORT Creates a centered heading. 

<CHECK _FOR_INCLUSION> Global Marks a file to ensure the file is included only 
once in the output. 

<CLOSING> LETTER Specifies the closing of a letter. 

<CO> Global Labels a callout in an example. The <CO> tag is 
identical to the <CALLOUT> tag. 

<CODE_EXAMPLE> Global Begins an example of code. Code consists 
of words or lines of instructions written in a 
programming language or a command language. 

<COLUMN> ARTICLE Specifies that a new column of output should 
begin in a two-column doctype. 

<COLUMN> REPORT Specifies that a new column of output should 
begin in a two-column doctype. 

<COMMAND> SOFTWARE Begins a new command description. 

<COMMAND_SECTION> SOFTWARE Begins a command reference section, enables 
tags reserved for use in command sections, and 
sets paging attributes. 

<COMMENT > Global Marks a portion of your SDML input file that 
you do not want to appear in your output. Text 
marked by a <COMMENT> tag is ignored by the 
tag translator during processing. 

<CONDITION> Global Marks a section of an SDML file that is not 
processed unless one of the arguments to 
the tag matches the argument in the related 
<SET_CONDITION> tag. 

<CONSTRUCT > SOFTWARE Specifies a variable construct and gives its 
expansion. 

<CONSTRUCT_LIST > SOFTWARE Begins a list of construct items and definitions 
that expand on variables specified in the context 
of the <STATEMENT_FORMAT> tag. 

<CONTENTS_FILE> Global Specifies that the table of contents output file 
for a document should be included when the 
document is processed. 

<COPYRIGHT_DATE> Global Inserts a copyright date line on the copyright 
page along with other system-specific copyright 
information. 

<COPYRIGHT_PAGE> Global Begins a copyright page and enables copyright 
page tags. 

<—CUP> Global Marks the continuation of a paragraph that has 


been interrupted by another text element. 
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Tag 
<CPAREN> 


<CPOS> 
<DATE> 
<DEFINE_BOOK_NAME> 


<DEFINE_SYMBOL> 


<DEFINITION_LIST > 


<DEFINITION_LIST_HEAD > 


<DEFLIST_DEF> 


<DEFLIST_ITEM> 


<DELAYED> 


<DELETE_KEY > 


<DESCRIPTION> 


<DISPLAY > 


<DISTLIST> 


<DOCTYPE> 


<DOCUMENT_ATTRIBUTES> 


<DOCUMENT_ATTRIBUTES> 


<DOCUMENT_ATTRIBUTES> 


<EMPHASIS> 


<ENDCOPYRIGHT_PAGE> 


Doctype 
Global 


SOFTWARE 
Global 
Global 


Global 


Global 


Global 


Global 


Global 


Global 


SOFTWARE 


SOFTWARE 


SOFTWARE 


LETTER 


Global 


ARTICLE 


REPORT 


SOFTWARE 


Global 


Global 


Description 


Supplies an unmatched closing parenthesis in an 
argument to a tag. 


Marks the cursor position in a screen display. 
Produces the current system date or time. 


Defines the title of a book and associates a 
user-defined symbol-name with that title for later 
reference. 


Associates a string of text with a user-defined 
symbol, so that the text can be referenced via 
this symbol throughout the document. 


Begins a definition list. 


Supplies the heading to precede a definition 
list. Output formatting is controlled by the 
document-type. 


Begins the text that defines an item in a definition 
list. 


Marks an item to be defined in a definition list. 


Allows you to specify text that contains SDML 
tags in an argument to another tag and delays the 
execution of those contained tags. 


Creates a special character resembling a DELETE | 
key on a keyboard. 


Begins a section of descriptive text providing 
detailed information on the current reference 
element. 


Simulates the appearance and position of 
characters on a terminal screen. 


Begins a list of persons to whom you want to 
distribute a memo or letter. 


Specifies the document type for your file. This 
tag is for informational purposes only. 


Enables doctype-specific tags that override the 
default design format of the ARTICLE doctype. 


Enables doctype-specific tags that override the 
default design format of the REPORT doctype. 


Enables doctype-specific tags that override 
the default design format of the SOFTWARE 
doctype. 


Marks a word or phrase for distinctive 
typographical treatment. 


Terminates the copyright page and optionally 
provides text that may be used on a document- 
type specific basis. 
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Tag 
<ENDPART_PAGE > 


<ENDTITLE_PAGE> 


<EXAMPLE> 
<EXAMPLES_INTRO> 
<EXAMPLE_ATTRIBUTES> 
<EXAMPLE_FILE> 


<EXAMPLE—SEQUENCE > 


<EXAMPLE_SPACE> 


<EXC> 


<EXI> 


<EXTEXT > 


<FARG> 


<FARGS> 


<FCMD> 


<FCMD> 


<FFUNC> 


<FIGURE> 


<FIGURE_ATTRIBUTES> 


<FIGURE_FILE> 


<FIGURE_SPACE > 


<FILE_SPEC> 


Doctype 
Global 


Global 


Global 
SOFTWARE 
Global 
Global 


SOFTWARE 


Global 


SOFTWARE 


SOFTWARE 


SOFTWARE 


SOFTWARE 


SOFTWARE 


Global 


SOFTWARE 


SOFTWARE 


Global 


Global 


Global 


Global 


Global 


Description 

Terminates a part page and optionally specifies 
paging attributes for text that follows. 
Terminates a title page and optionally specifies 
text to appear at the bottom of the title page. 
Labels the beginning of a formal example. 
Provides introductory text before an example. 
Specifies attributes for the current example. 


Causes a separate file containing an example to 
be included in the source file. 


Begins a numbered sequence of informal 
examples. 


Leaves space for an example that will be pasted 
in during final production. 


Begins a code example within a series of 
numbered informal examples. 


Begins an interactive example within a series of 
numbered informal examples. 


Terminates an example and begins an explanation 
in a sequence of numbered examples. 


Adds a single argument line to a list of arguments 
in a routine syntax format section. 


Provides the argument portion of a routine syntax 
statement within the context of the <FORMAT> 
tag. 


Specifies the keyword portion of a formatted 
command/parameter pair in a format section. 


Identifies a command or statement keyword, 
and an optional parameter list, within a format 
section. 


Labels a function within the context of a 


<FORMAT> or <STATEMENT_FORMAT> tag 
section. 


Labels the beginning of a figure. 
Specifies the placement of a figure on the page. 
Also specifies valid page breaks for that figure. 


Includes a graphics file in your output file if the 
output device has graphics capability. 


Marks the space required for a figure that will be 
pasted in during final production. 


Allows you to use a file specification that 
contains angle brackets as an argument to an 
SDML tag without VAX DOCUMENT interpreting 
that file specification as a tag. 
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Tag 
<FINAL CLEANUP > 


<FOOTNOTE> 


<FOOTNOTE_TEXT> 


<FOOTREF> 


<FORMAT > 


<FORMAT> 


<FORMAT_SUBHEAD> 


<FPARM> 


<FPARM> 


<FPARMS> 


<FPARMS> 


<FROM_ADDRESS > 


<FRONT_MATTER> 


<FRTN> 


<FTAG> 


<FUNCTION> 
<GDEF> 
<GLOSSARY > 


<GRAPHIC> 


Doctype 
Global 


Global 


Global 


Global 


Global 


SOFTWARE 


SOFTWARE 


Global 


SOFTWARE 


Global 


SOFTWARE 


LETTER 


Global 


SOFTWARE 


SOFTWARE 


SOFTWARE 
Global 
Global! 


SOFTWARE 


Description 


Provides explicit formatting instructions for the 
text formatter to be used for final formatting and 
cleanup. 


Places a footnote character in text, using the 
character specified in the tag’s argument, and 
places the footnote text at the bottom of the 
page. 

Specifies the text of a footnote associated with a 
footnote reference. 


Creates one or more footnote callouts in text 
or in a table using the footnote numbers or 
characters as arguments. 


Enables <FCMD> , <FPARMS> , and <FPARM> 
to distinguish formatted command keywords and 
parameters. 


Begins a section that highlights the syntax of a 
tag, command, or routine, including keywords 
and arguments. 


Introduces one of the multiple formats in the 
statement format section. 


Specifies a parameter to be formatted following 
<FPARMS> , aligned under the parameter list 
portion of a keyword/parameter list pair. 


Adds a single parameter line to a list of 
parameters in a command or statement syntax 
format section. 


Specifies the parameter portion of a formatted 
command/parameter pair in a format section. 


Specifies the parameters to a command or 
statement keyword. 


Specifies the name and address of the sender of 
a letter, and places this information flush left near 
the right margin. 


Begins the front matter of a book. 


Specifies the routine-keyword portion of a routine 
syntax statement within the context of the 
<FORMAT> tag. 


Specifies the name of a tag and its arguments 
within the context of a <FORMAT> tag. 


Begins a new function description. 
Begins the text that defines a term in a glossary. 


Begins a glossary of terms in a document or 
book. 


Displays terminal graphics characters. 
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Tag 
<GREF> 


<GTERM> 
<HEAD> 


<HEAD> 
<HEADx> 


<HELLIPSIS> 
<HYPHENATE> 


<ICON> 


<ICON_FILE> 


<ICON_TEXT > 


<INCLUDE> 
<INCLUDES_FILE> 


<INDEX _FILE> 


<INTERACTIVE> 


<INTRO_SUBTITLE > 
<INTRO_TITLE> 


<KEEP> 


<KEY> 
<KEYPAD> 


<KEYPAD_ENDROW > 


Doctype 
Global 


Global 
LETTER 


REPORT 


Global 


Global 
Global 


Global 


Global 


Global 


Global 


Global 


Global 


Global 


OVERHEADS 


OVERHEADS 


Global 


SOFTWARE 


SOFTWARE 


SOFTWARE 


Description 


Marks a cross-reference to a term within a 
glossary. 


Labels a term to be defined in a glossary. 


Creates a main heading which is placed on the 
left side of the page. 


Creates a main heading which is placed on the 
left of the output page. 


Marks a heading of the level specified (1 through 
6). 


Labels omitted material in a horizontal dotted line. 


Provides information about legal hyphenation of a 
word of text. 


Allows you to include a graphic image in your 
printed output and print text parallel to the image. 
The text is printed either to the right or left of the 
picture. 


Specifies a graphics file that accompanies text 
within the <!ICON> and <ENDICON> tags. 


Labels the text that accompanies a graphic image 
included in text with the <ICON> and <END_ 
ICON> tags. 


Causes the contents of a specified file to be 
included in the current input file for processing. 


Equates a logical name with a file specification 
during processing of a profile. 


Specifies the position in a book (or document) 
where an index file should be included in the 
output. 


Begins an example dialog between user and 
system and enables the tags <S> and <U> to 
distinguish system text from user text. 


Creates a secondary title of up to four lines on an 
introductory slide. 


Creates a main title of up to four lines on an 
introductory slide. 


Specifies that a string of text should always occur 
on the same line of output, that is, should not be 
hyphenated between lines. 


Depicts a key from a keyboard or keypad 
graphically. 


Specifies an individual keypad diagram and 
optionally supplies a title for that.diagram. 


Displays the bottom row of an editing keypad 
that has up to three keys. 
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Tag 
<KEYPAD_ROW > 


<KEYPAD_SECTION> 


<KEYWORD> 


<KEY_NAME> 
<KEY_PLUS> 


<KEY_SEQUENCE > 


<KEY_TYPE> 


<LE> 
<LEVEL> 


<LINE> 


<LINE_ART > 


<LIST> 


<LITERAL> 


<LOWERCASE> 


<MARK> 


<MATH> 


<MATH_CHAR> 
<MCS> 


<MEMO_DATE> 


<MEMO_FROM> 


<MEMO_HEADER> 


<MEMO_LINE> 


Summary of VAX DOCUMENT Tags 


Doctype 
SOFTWARE 


SOFTWARE 
Global 


SOFTWARE 
SOFTWARE 


SOFTWARE 


SOFTWARE 


Global 
REPORT 


Global 


Global 


Global 


Global 


Global 


Global 


Global 


Global! 
Global 


LETTER 


LETTER 


LETTER 


LETTER 


Description 

Displays a row of an editing keypad that has up 
to four keys. 

Begins a series of one or more keypad diagrams. 


Labels a significant word that deserves to be 
distinguished typographically. 


Emphasizes the name of a key within text. 


Creates a plus sign between keys in a key 
sequence example. 


Begins a section containing one or more key 
representations. 


Provides a descriptive label for keys within a key 
sequence. 


Labels a list element. 


Specifies an outline entry and the organizational 
level of that outline entry. 


Specifies that the text that follows is to be placed 
on a new line of output. 


Labels a rough sketch produced at the terminal 
keyboard for draft output, to give some idea of 
what the final figure will look like. 


Begins a list. The type of list (for example, 
numbered or stacked) is specified by the 
argument to the <LIST> tag. 


Allows you to specify text that contains words 
in angle brackets that might otherwise be 
interpreted as tags. 


Labels text that should appear as lowercase in 
the final output. 


Indicates the beginning of new or modified 
information. 


Labels a short mathematical expression or the 
beginning of an extended mathematical example. 


Creates a special mathematical symbol. 


Labels a character in the DEC Multinational 
Character Set. 


Creates a line in a memo or letter that displays 
the date after the heading “Date:”. 


Identifies the name and address of the sender of 
a memo, and places this information flush left on 
the left margin, with a heading of “From:”. 


Centers the heading “Interoffice Memorandum” in 
bold letters on the current output line. 


Lets you create your own titled informational 
lines. 
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Tag 
<MEMO_TO> 


<MESSAGE_SECTION> 
<MESSAGE_TYPE> 
<MSG> 

<MSGS> 


<MSG_TEXT> 


<NESTED_TABLE_BREAK> 


<NEWTERM> 
<NOTE> 


<OPAREN> 

<ORDER_NUMBER> 
<OUTLINE> 

<OVERVIEW> 


<P> 
<PAGE> 


<PARAMDEF> 
<PARAMDEFLIST > 
<PARAMITEM> 
<PARENDCHAR> 
<PART> 


<PART_PAGE> 


Doctype 
LETTER 


SOFTWARE 
SOFTWARE 
SOFTWARE 
SOFTWARE 
SOFTWARE 
Global 


Global 
Global 


Global 
Global 
REPORT 
SOFTWARE 


Global 
Global 


SOFTWARE 
SOFTWARE 
SOFTWARE 
Global 
Global 


Global 


Description 


Specifies the name and address of the receiver of 
a memo, and places this information flush left on 
the left margin, with a heading of “To:". 


Begins a section of error message descriptions. 


Establishes the format for error messages and 
affects the numbers of arguments passed to the 
<MSG> and <MSGS> tags. 


Formats the text of a message within a series of 
error message descriptions. 


Formats the text of one or more messages within 
a series of error message descriptions. 


Labels text which describes a message in a 
<MESSAGE_SECTION> tag section. 


Marks a place that a nested table may be broken 
across pages. 


Labels a term first introduced into the text in 
order to emphasize the term. In output, the term 
will be italicized. 


Labels a note, caution, warning, or some other 
portion of text to which you wish to draw 
attention. 


Supplies an unmatched opening parenthesis in an 
argument to a tag. 


Labels the order number or part number that may 
appear on the title page of a book. 


Begins an outline and specifies a title for the 
outline. 


Provides a summary description of a reference 
element. 


Marks the beginning of a new paragraph. 


Breaks a page of text, forcing the text that 
follows the tag to begin on a new page. 


Begins the text that defines an item in a 
parameter definition list. 


Begins a definition list describing zero or more 
parameters or arguments. 


Labels one to seven items to be defined in a 
parameter definition list. 


Labels a character that will appear alone within 
parentheses to achieve better spacing. 


Labels the start of a major division within a 
document, and starts it on a new page. 


Begins a divider page for a new part of a 
document. 
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Tag 
<PREFACE> 
<PREFACE_SECTION> 


<PRINT_DATE> 
<PROFILE> 


<PROMPT > 


<PROMPTS> 


<QPAIR> 
<QUALDEF> 


<QUALDEFLIST > 


<QUALITEM> 


<QUAL_LIST> 


<QUAL_LIST_DEFAULT_ 


HEADS> 
<QUAL —LIST_HEADS > 


<QUOTATION> 


<QUOTE> 
<REFERENCE > 


<REF_NOTE> 
<REF_NOTES> 


<RELATED_ITEM> 


<RELATED_TAG> 


<RELATED_TAGS> 
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Doctype 


Global 
Global 


Global 
Global 


SOFTWARE 


SOFTWARE 


SOFTWARE 
SOFTWARE 


SOFTWARE 


SOFTWARE 


SOFTWARE 
SOFTWARE 


SOFTWARE 


ARTICLE 


Global 
Global 


ARTICLE 


ARTICLE 


SOFTWARE 


SOFTWARE 


SOFTWARE 


Description 


Labels the beginning of a preface. 


Creates a major section in the preface of a 
book, to contain information such as a summary 
of changes to the book or other relevant 
information. 


Inserts a print date line on the copyright page. 
Indicates that the source file is a profile and that 
a bookbuild is to be performed. 


identifies a prompt which appears on a separate 
line from other prompts, and any parameters 
associated with that prompt. 


Begins a summary of interactive prompts. 

Labels a qualifier pair within a qualifier format list. 
Begins the text that defines an item in a qualifier 
definition list. 

Begins a definition list describing zero or more 
command qualifiers. 

Labels one to seven items to F2 defined in a 
qualifier definition list. 

Begins a qualifier summary list. 


Modifies the default heading used by the 
<QUAL_LIST> tag. 


Labels the headings you want to use for one or 
both of the columns in a qualifier format list when 
<QUAL_LIST> (SPECIAL) is used in unusual cases 
for formatting control. 


Begins a quotation in which the spacing is 
retained and the text is not filled or justified. 


Labels quoted material in the output. 


Makes a reference to a symbol-name in a book 
element or text element. When processed, 
<REFERENCE> is replaced with the current value 
of the symbol-name. 


Specifies the text of a reference note, and creates 
a bracketed reference number in the article text. 


Causes all accumulated reference notes to be 
output. 


Provides a text description of a set of tags or the 
usage of a set of tags that may be related to the 
tag being described. 


Specifies a single tag that is related to the current 
tag. 


Provides a summary of tags whose usage is 
related to the tag being described. 
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Tag 
<RESTRICTIONS> 


<RETTEXT > 
<RETURNS> 
<RETURN_VALUE> 
<REVISION> 


<REVISION_INFO> 


<RIGHT_LINE> 


<RITEM> 

<ROUTINE> 
<ROUTINE_SECTION> 
<RSDEFLIST> 


<RSITEM> 


<RULE> 
<RUNNING_FEET > 
<RUNNING_FEET > 


<RUNNING_FEET > 
<RUNNING_FEET > 
<RUNNING_TITLE> 


<RUNNING_TITLE> 
<RUNNING_TITLE> 
<RUNNING_TITLE> 
<S> 


<SALUTATION> 
<SAMPLE_TEXT > 
<SDML_—TAG> 


Doctype 
SOFTWARE 


SOFTWARE 
SOFTWARE 
SOFTWARE 
Global 


Global 


Global 


SOFTWARE 
SOFTWARE 
SOFTWARE 
SOFTWARE 


SOFTWARE 


Global 
ARTICLE 
OVERHEADS 


REPORT 


SOFTWARE.SPEC 


ARTICLE 


OVERHEADS 


REPORT 


SOFTWARE.SPEC 


Global 


LETTER 
Global 
SOFTWARE 


Description 


Labels the restrictions on the use of a reference 
element within a SOFTWARE reference template. 


Provides general information about the attributes 
of the value returned by the routine. 


Provides information about the value returned by 
a routine. 


Labels a character string return value. 


Indicates that the document contains either new 
or modified information and enables the output of 
the <MARK> tag. 


Labels a section on a title page that provides 
information on what previous books have been 
superseded by the current one. 


Specifies a line of text that is to be right-adjusted 
in the current text margin. 


Labels an item in a list of restrictions. 
Begins a new routine description. 


Begins a routine reference section, enables tags 
reserved for use in routine sections, and sets 
paging attributes. 


Begins a return status definition list in the routine 
template. 


Specifies the return status value of a routine and 
lists its meaning. 


Outputs a rule within a table. 
Creates a heading at the bottom of each page. 


Specifies text to be placed at the bottom of the 
next slide and all subsequent slides. 


Creates a heading at the bottom of each page. 
Creates a heading at the bottom of each page. 


Creates a one or two line running heading at the 
top of each page. 


Specifies text to be placed at the top of the next 
slide and all subsequent slides. 


Creates a one or two line running heading at the 
top of each page. 


Creates a one or two line running heading at the 
top of each page. 


Labels the system portion of a dialog between 
user and system in an interactive example. 


Specifies the salutation for the letter. 
Distinguishes, typographically, an extract of text. 
Begins a new tag description. 


D-11 


Summary of VAX DOCUMENT Tags 


Table D—1 (Cont.) Summary of VAX DOCUMENT Tags 


Tag 
<SECTION> 


<SET_APPENDIX _LETTER> 
<SET_APPENDIX _NUMBER> 
<SET_CHAPTER_NUMBER> 
<SET_CONDITION> 
<SET_FIGURE _FILE_SPACING_ 
DEFAULT > 
<SET_TABLE_ROW_BREAK _ 


DEFAULT > 
<SET_TEMPLATE_COMMAND > 


<SET_TEMPLATE_HEADING> 
<SET_TEMPLATE_LIST > 
<SET_TEMPLATE_PARA> 


<SET_TEMPLATE_ROUTINE> 


<SET_TEMPLATE_ 
STATEMENT > 


<SET_TEMPLATE_ 
SUBCOMMAND> 


<SET_TEMPLATE_TABLE> 
<SET_TEMPLATE_TAG> 
<SHOW-_LEVELS> 
<SIGNATURES > 


<SIGNATURES> 
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Doctype 
REPORT 


Global 
MILSPEC 
Global 
Global 
Global 
Global 


SOFTWARE 


SOFTWARE 
SOFTWARE 
SOFTWARE 


SOFTWARE 


SOFTWARE 


SOFTWARE 


SOFTWARE 
SOFTWARE 
REPORT 
REPORT 


SOFTWARE 


Description 


Begins a new page and creates a major heading 
on the left side of that page. 


Overrides the default appendix letter assigned to 
an appendix by VAX DOCUMENT. 


Overrides the default appendix roman number 
assigned to an appendix by VAX DOCUMENT. 


Overrides the default chapter number assigned to 
a chapter by VAX DOCUMENT. 


Creates or removes a condition-name. 


Overrides the default amount of vertical blank 
space that appears before and after an included 
graphics file. 


Overrides the default value for a multipage table's 
first valid break. 


Defines a new tag with the same function as the 
<COMMAND> tag, and changes the format of 
command descriptions produced using the new 
tag. 


Overrides the heading for all subsequent uses of 
a template tag. 


Creates a user-defined set of tags for listing 
information. 


Defines a set of template tags for setting the 
format of a paragraph of information. 


Defines a new reference element tag name to 
use in the routine template, and specifies the 
formatting attributes for the new tag. 


Defines a new reference element tag name to 
use in the statement template, and specifies the 
formatting attributes for the new tag. 


Changes the name of the <SUBCOMMAND> tag 
to the name you specify, and specifies formatting 
attributes for the new tag. 


Defines a set of template tags for setting 
information in two- or three-column lists. 


Defines a new reference element tag name to 
use in the tag template, and specifies formatting 
attributes for the newly-defined tag. 


Emphasizes text within an outline. 


Begins a list of signatures which are to appear in 
the front matter of a document. 


Begins a list of signatures which are to appear in 
the front matter of a document. 
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Tag 
<SIGNATURE_LINE> 


<SIGNATURE_LIST > 


<SINGLE_QUOTE> 


<SLIDE> 
<SOURCE_NOTE> 


<SPECIAL _CHAR> 


<SPECIFICATION_INFO> 


<SPEC_TITLE> 
<STATEMENT > 
<STATEMENT_FORMAT > 
<STATEMENT_LINE> 


<STATEMENT_SECTION> 


<SUBCOMMAND> 
<SUBCOMMAND_SECTION> 


<SUBCOMMAND_SECTION_— 
HEAD> 


<SUBHEADx> 
<SUBJECT > 


<SUBTITLE> 
<SUBTITLE> 


<SUBTITLE> 


Doctype 
MILSPEC 


MILSPEC 


Global 


OVERHEADS 
ARTICLE 


Global 


MILSPEC 


MILSPEC 


SOFTWARE 


SOFTWARE 


SOFTWARE 


SOFTWARE 


SOFTWARE 
SOFTWARE 
SOFTWARE 
Global 
LETTER 
ARTICLE 


MILSPEC 


OVERHEADS 


Description 


Creates up to two rules on a line and places a 
name below each rule; each rule is used as a 
signatory line for the person listed below it. 


Begins a two-column listing of signature lines 
on the title page of a document and supplies 
headings for each of those columns. 


Outputs, within text, a single quotation mark as it 
appears on a keyboard. 


Begins a new overhead slide. 


Provides information pertaining to the original 
source of information for an article. 


Provides access to special characters that are not 
available on the terminal keyboard. 


Creates a listing of information about the 
specification on the title page and creates a 
two-line running heading for the rest of the 
document. 


Creates a title with up to seven centered lines on 
the title page. 


Begins a new statement description. 


Begins a section that illustrates the syntax of a 
statement or function including keywords and 
parameters. 


Indicates the position of a valid statement line 
within the context of a statement format or a 
construct list. 


Begins a statement reference section, enables 
tags reserved for use in statement sections, and 
sets paging attributes. 


Begins a new subcommand description. 


Begins a subcommand reference section within 
the command section. Use this section of a 
reference document for subordinate commands. 


Specifies the heading for text that precedes a 
subcommand section. 


Marks an unnumbered subsidiary heading. 


Specifies the subject of a memo or letter 
and places this information with a heading of 
“Subject:” at the left margin. 


Specifies a subtitle for an article. 


Creates a subtitle with up to seven centered lines 
on the title page. 


Specifies a secondary title line for a new slide. 
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Tag 
<SYNTAX> 


<SYNTAX_—DEFAULT_HEAD> 


<TABLE> 
<TABLE_ATTRIBUTES> 
<TABLE_FILE> 


<TABLE_HEADS> 
<TABLE_KEY > 
<TABLE_KEYREF > 
<TABLE_ROW> 
<TABLE_ROW_BREAK> 


<TABLE_SETUP> 


<TABLE_SPACE> 
<TABLE_UNIT> 


<TABLE_UNIT_HEADS> 
<TAG> 
<TAG_SECTION> 


<TERMINATING_TAG> 
<TEXT_SIZE> 


<TITLE> 
<TITLE> 


<TITLE> 
<TITLE_PAGE> 


<TITLE_SECTION> 


<TOPIC> 
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Doctype 
SOFTWARE 


SOFTWARE 


Global 
Global 
Global 


Global 


Global 


Global 


Global 


Global 


Global 


Global 


Global 


Global 
Global 
SOFTWARE 


SOFTWARE 


OVERHEADS 


ARTICLE 
Global 


OVERHEADS 
Global 


ARTICLE 


OVERHEADS 


Description 
Labels a statement that illustrates the syntax of a 
programming language. 


Creates a default heading for the <SYNTAX> 
tag. 


Begins a sequence of columnar data. 
Requests special formatting. 


Causes a separate file containing a formal table to 
be included in the SDML input file. 


Specifies column headings for each column in the 
table. 


Begins a key or legend for a table. 


Specifies that a table key should be printed below 
the table (or portion of the table) in which this tag 
appears. 


Specifies text for each column in the current 
table. 


Specifies the boundaries within which a long table 
can be broken onto a new page. 


Declares the number of cojumns in a table and 
the effective (approximate) width values to be 
assigned to each column. 


Marks the space required for a table that will be 
pasted in during final production. 


Begins a portion of a table containing rows that 
are to be grouped as logical units. 


Specifies headings to be used for a table unit. 
Labels a tag. | 


Begins a tag reference section, enables tags 
reserved for use in tag sections, and sets paging 
attributes. 


Specifies the required terminator for a tag. 


Changes the size of type used within the context 
of topics, tables, and lists. 


Specifies the main title line for an article. 


Labels the title used on either a title page or part 
page. 
Specifies a title line for a new slide. 


Labels the beginning of a title page and enables 
the title page tags. 


Begins the title section of an article which spans 
both columns of the article. 


Specifies a line of topic text for a slide. 
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Tag 


<TO_ADDRESS> 


<U> 


<UNDERLINE > 
<UPDATE—RANGE> 


<UPPERCASE> 
<USER_I_MESSAGE> 
<USER_W_MESSAGE> 
<VALID_BREAK> 
<VALID_TABLE_ROW_BREAK> 


<VARIABLE> 
<VBAR> 


<VITA> 
<X> 


<Y> 


Doctype 
LETTER 


Global 


Global 
Global 


Global 


Global 


Global 


Global 


Global 


Global 
Global 


ARTICLE 


Global 


Global 


Description 


Identifies the name and address of the receiver of 
a letter and places this information flush left on 
the left margin. 


Labels the user portion of a dialog between user 
and system in an interactive example. 


Marks a portion of text to be underlined. 


Marks the location at which a new section of 
updated pages begins. 


Labels text that should appear as uppercase in 
the final output. 


Sends an informational message to the terminal 
or log file during processing of a file. 


Sends a warning message to the terminal or log 
file during processing of a file. 


Labels a permissible page break within a 
monospaced example. 


Marks a permissible place that a first-level table 
row may be broken across pages. 


Labels a program variable or number. 


Labels an occurrence of a vertical bar in an 
argument to a tag. 


Provides information about the author’s 
professional history. 


Creates an index entry with a reference to the 
page on which this tag appears. 


Creates an index entry with no reference to 
the page on which this tag appears. Used for 
cross-references (“See” or “See also” entries). 
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Index 





A 


<ABSTRACT> 
definition of © 9-2 
< ACCENT > 
definition of © 9-3 
< ALIGN_AFTER> 
definition of ¢ 9-4 
<ALIGN_CHAR> 
definition of ¢9-5 to 9-6 
<ALIGN_NUMBER> 
definition of °9-7 to 9-8 
< AMPERSAND > 
definition of © 9-9 
Angle bracket in text 
coding an® 2—3 
Appendix 
creating ® 3-5 
< APPENDIX > 
definition of ¢9—10 
Arguments to tags 
See Tags 


Backslash 

coding a® 2—5 
<BACKSLASH> 

definition of ¢ 9—11 
<BAR_CHAR> 

in math expressions ® 9-146 
/BATCH qualifier ¢ A—5 
Bolding text 

See Emphasizing text 
Bookbuilding ® 1-9, 4-9 
Book element 

definition of © 1-9 
<BOX> 

definition of 9-12 
Boxes, creating in text 

See <sox> 








C 


<CALLOUT> 

definition of ©¢9—13 
<CALLOUTS> 

definition of ©9-—15 to 9-16 
<CALLOUT_REF> 

definition of ©9-—14 
Centered headings, creating 

See <CHEAD> 
<CENTER_LINE> 

definition of ©9-17 
Change bars 

See <mark> 
<CHAPTER> 

definition of ¢9-—18 
Chapters 

creating ® 3—2 
<CHEAD> 

definition of ©9—19 
<CHECK_FOR_INCLUSION> 

definition of 9-20 to 9-21 
<CO> 

definition of © 9-22 
<CODE_EXAMPLE> 

definition of ©9-23 to 9-25 
Command line 

See DOCUMENT command 
<COMMENT> 

definition of °9-26 to 9-27 
<CONDITION> 

definition of °9-28 to 9-30 
Conditionalized book elements 

building * 4-14 
/CONDITION qualifier ¢ A-6 
/CONTENTS qualifier *° A-6 
<CONTENTS_FILE> 

definition of © 9-31 
Copyright page 

creating ® 3—4 
<COPYRIGHT_DATE > 

definition of © 9-32 
<COPYRIGHT_PAGE> 

definition of © 9-33 
<CP> 


definition of ¢9—34 


Index—1 


Index 


<CPAREN> 
definition of © 9-35 
Cross-reference file ¢ 6—2 


D 


<DATE> 
definition of °9-—36 to 9-37 
<DEFINE_BOOK_NAME> ® 9-38 
definition of °9-38 to 9-39 
<DEFINE_SYMBOL> 
definition of ©9-—40 to 9-41 
<DEFINITION_LIST> 
definition of 9-42 to 9-43 
<DEFINITION_LIST_HEAD> 
definition of © 9-44 
<DEFLIST_DEF> 
definition of °9—45 
<DEFLIST_ITEM> 
definition of * 9-46 
Degree character 
See <mcs> 
<DELAYED> 
definition of ©°9-47 to 9-48 
Destination 
See DOCUMENT command, destination 
parameter 
/DEVICE_CONVERTER qualifier © A—7 
/DIAGNOSTICS qualifier ¢ A-9 
Doctype 
See DOCUMENT command, doctype parameter 
<DOCTYPE> 
definition of °9—49 to 9-50 
Documentation set 
VAX DOCUMENT e 1-1 
DOCUMENT command 
introduction to® 1-4 
parameters ® A—2 to A-5 
destination ¢ A—4 
doctype ® A-3 
input-file-spec ® A-2 
qualifiers®¢ A—5 to A-16 
/BATCH® A-5 
/CONDITION ¢ A-6 
/CONTENTS ® A-6 
/DEVICE_CONVERTER ® A-—7 
/DIAGNOSTICS ¢ A-9 
/ELEMENT ® A-9 
/INCLUDE e A-9 





Iindex—2 


DOCUMENT command 
qualifiers (cont’d.) 
/INDEX ¢ A-9 
/KEEP® A-12 
/LIST ® A-—12 
/LOG*® A~12 
/MAP® A-13 
/MASTER_INDEX ® A-13 
[OUTPUT ¢ A-13 
/PRINT ® A-—14 
/PROFILE e A—15 
/SYMBOLS ¢ A-16 
/TAG_TRANSLATOR ® A-—16 
/TEXT_FORMATTER ® A-—16 
summary of ® A-1 to A-17 
syntax of © A-2 
Document type 
See DOCUMENT command, doctype parameter 
<DOT_CHAR> 
in math expressions ® 9-146 
<DOUBLE_QUOTE> 7 
definition of ¢9-51 to 9-52 


E 


Editors 
See LSE 





/ <ELEMENT> 


definition of ¢ 9-53 
/ELEMENT qualifier ¢ A~9 
<ELLIPSIS> 

definition of ¢ 9-54 
<EMPHASIS> 

definition of °9-55 to 9-56 
Emphasizing text® 8-1 to 8-3 
<ENDCOPYRIGHT_PAGE > 

definition of © 9-57 
<ENDPART_PAGE> 

definition of ° 9-58 
<ENDTITLE_PAGE> 

definition of © 9-59 
Equations, creating 

See <MATH> 
Error messages 

See Messages 
<EXAMPLE> 

definition of ©9-—60 to 9-62 
Examples 

creating ®° 3-19 


Examples (cont’d.) 

formal ® 3—20 

informal ¢ 3—20 
<EXAMPLE_ATTRIBUTES> 

definition of °9-63 to 9-66 
<EXAMPLE_FILE> 

definition of © 9-67 
<EXAMPLE_SPACE> 

definition of °9-68 to 9-69 


F 


<FCMD> 

definition of °¢9—70 to 9-72 
<FIGURE > 

definition of °9—72 to 9-80 
Figures 

controlling attributes of °3—-16 

creating ® 3-14 

margins in® 3-16 

page breaks in® 3-17 
*<FIGURE ATTRIBUTES > 

definition of ©9-81 to 9-82 
<FIGURE_FILE> 

definition of °9-—83 to 9-86 
<FIGURE_SPACE> 

definition of °9—87 to 9-88 
File building * 4—2 
File specifications 

coding in tag arguments ® 2—4 
<FILE_SPEC> 

definition of °9—89 to 9-90 
<FINAL CLEANUP > 

definition of 9-91 to 9-92 
<FOOTNOTE> 

definition of ¢9-—93 to 9-95 
Footnotes 

effect on page breaking in tables © 3-12 
<FOOTNOTE_TEXT> 

definition of °9—96 to 9-97 
<FOOTREF> 

definition of 9-98 to 9-99 
<FORMAT> 

definition of ©9—100 
<FPARM> 

definition of © 9-101 
<FPARMS> 

definition of °9—102 
<FRONT_MATTER> 


definition of °9-—103 to 9-104 
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<GDEF> 
definition of *9-105 
Generic markup language 
See also SDML file 
definition of * 1-3 
Global tags ® 2-1 
Glossary 
creating ® 3—5 
<GLOSSARY > 
definition of °9—106 to 9-107 
Graphics files 
included in SDML files * 3-18 
<GREF> 
definition of © 9-108 
<GTERM> 
definition of © 9-109 


H 


<HAT> 

in math expressions ® 9-146 
<HAT_CHAR> 

in math expressions ® 9-146 
Headings 

creating ® 3-2 
<HEADX> 

definition of €9-—110 to 9-111 
<HELLIPSIS> 

definition of °9—112 
Hyphen 

coding in text * 2-6 
<HYPHENATE> 

definition of °9-113 





Soa a A a aE 
<ICON> 
definition of ©9-—114 to 9-115 
<ICON_FILE> 
definition of ©9-116 to 9-117 
<ICON_TEXT> 
definition of © 9-118 


<INCLUDE> 
definition of ©9—119 
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index 


/INCLUDE qualifier ¢ A—9 
<INCLUDES_FILE> 

definition of ¢9—120 to 9-121 
Index and <revision> tag® 9-195 
/INDEX qualifier ® A—9 
<INDEX _FILE> 

definition of °9-122 
Input file 

See SDML file 
<INTERACTIVE> 

definition of °9—123 to 9-124 
Italicizing text 

See Emphasizing text 


K 


<KEEP> 
definition of ¢9-—125 
/KEEP qualifier ® A—12 
<KEYWORD> 
definition of ©9-—126 


L 


Language-Sensitive Editor 

See LSE 
<LE> 

definition of ©9-127 
<LINE> 

definition of ©9—128 to 9-130 
<LINE_ART> 

definition of ©9—131 to 9-132 
<LIST> 

definition of ©9—133 to 9-139 
/LIST qualifier® A—12 
Lists 

creating various types ® 3—5 
<LITERAL> 

definition of ©9-—140 
Logical names ® 4—1 1 
/LOG qualifier®¢ A-12 
<LOWERCASE > 

definition of °9-141 
LSE*®B-1 to B-8 

VAX DOCUMENT tokens and placeholders © 

B-8 
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/MAP qualifier ® A—13 
<MARK> 

definition of °9-—142 to 9-143 
/MASTER_INDEX qualifier A—13 
<MATH> 

definition of °9-144 to 9-156 
<MATH_CHAR> ® 9-157 

definition of 9-157 to 9-165 
<MCS> 

definition of °9-—166 to 9-169 
Messages 

general syntax of © 5—1 

summary of ®C—1 to C-81 


N 


Nested tables 

See Tables, nested 
<NESTED_TABLE_BREAK> 

definition of °9-—170 to 9-171 
<NEWTERM> 

definition of °9-—172 
<NOTE> 

definition of 9-173 


O 


<OPAREN> 
definition of °9—174 
<ORDER_NUMBER> 
definition of °9-—175 
Output device, specifying to DOCUMENT 
command 
See DOCUMENT command, destination 
parameter 
/OUTPUT qualifier® A-13 
<OVERLINE> 
in math expressions ® 9-146 
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<P> 
definition of ©9-176 to 9-177 
<PAGE> 
definition of ¢9—178 to 9-179 
Paragraphs 
creating ® 3-1 
Parameters, DOCUMENT command 
See DOCUMENT command, parameters 
<PARENDCHAR> 
definition of ¢9—180 to 9-181 
Parentheses in an argument 
coding * 2—5 
<PART> . 
definition of °9—182 to 9-183 
<PART_PAGE> 
definition of * 9-184 
Preface 
creating * 3—4 
<PREFACE> 
definition of °9-185 
<PREFACE_SECTION> 
definition of °9—186 
Printing 
an existing file * 4—5 
/PRINT qualifier A—14 
<PRINT_DATE> 
definition of © 9-187 
Processing ® 4—1 to 4—15 
bookbuilding ® 4—9 
element building ® 4—13 
individual input files (book elements) ® 4—2 
steps of ® 1-6, 4-9 
subelement building * 4—14 
Profile 
creating ®° 4—10 
example of *4—10 
preliminary ® 6-6 
processing 
See also Bookbuilding 
valid tags of °4—10 
<PROFILE> 
definition of °9—188 to 9-189 
/PROFILE qualifier ¢ A—15 


Index 





01 


Qualifiers 
See DOCUMENT command, qualifiers 
for controlling file processing * 4—3 
<QUOTE> 
definition of ¢9—190 to 9-191 


R 


<REFERENCE> 
definition of ©9—192 to 9-194 
Referencing symbol-names 
See Symbol-names 
<REVISION> 
definition of ©9—195 to 9-196 
<REVISION_INFO> 
definition of ©9—197 
<RIGHT_LINE> 
definition of °9—198 
<RULE> 
definition of ©9—199 


S 


<S$> 

definition of ©9—200 to 9-201 
<SAMPLE_TEXT> 

definition of ©9—202 
Scientific characters, creating 








See <MATH_CHAR> 
SDML file 

coding ® 2-2 

creating®2—1 to 2-7 

specifying to DOCUMENT command 

See DOCUMENT command, input-file-spec 
parameter 

<SET_CONDITION> 

definition of ©*9-—207 
<SET_FIGURE_FILE_SPACING_DEFAULT > 

definition of °9—208 to 9-209 
<SET_TABLE_ROW_BREAK_DEFAULT > 


definition of ©9-—210 to 9-211 
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<SINGLE_QUOTE > 

definition of ©9-—212 to 9-213 
<SPAN> 

definition of ©9—-214 to 9-216 
<SPECIAL_CHAR> . 

definition of ©9-217 to 9-218 
<SUBHEADx> 

definition of ¢9-—219 
Symbol definitions file ¢ 6—6 
Symbol-names 

controlling the output of references to 

See also <REFERENCE> © 6-4 

for text and book elements ® 6-2 

referencing ° 6—4 

referencing in other files 6—6 

rules for creating ® 6-1 

storing in cross-reference file ¢ 6—2 
/SYMBOLS qualifier © A-16 
Syntax 

See DOCUMENT command, syntax of 


7 


Tab characters 

in SDML files © 2—7 
<TABLE> 

definition of °9—220 to 9-221 
Table of Contents and <revision> tag® 9-195 
Tables 

controlling attributes of ¢ 3-9 

creating ® 3-6 

margins in® 3—10 

nested 

‘page breaks in® 3-13 

page breaks in® 3-11 to 3-14 
<TABLE_ATTRIBUTES > 

definition of °9-—222 to 9-223 
<TABLE_FILE> 

definition of ©9-224 to 9-225 
<TABLE_HEADS> 

definition of © 9-226 
<TABLE_KEY > 

definition of °9-227 to 9-228 
<TABLE_KEYREF> 

definition of ©9—229 
<TABLE_ROW> 

definition of ©9—230 to 9-231 
<TABLE_ROW_BREAK> 

definition of ©9-—232 to 9-234 
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<TABLE_SETUP> 
definition of © 9-235 to 
<TABLE_SPACE> ® 9-237 
definition of © 9-237 to 
<TABLE_UNIT> 
definition of *9-239 to 
<TABLE_UNIT_HEADS> 
definition of °9-—241 to 


9-236 
9-238 
9-240 


9-242 


<TAG> 
definition of © 9-243 
Tags 
arguments to ® 2-2 
context-sensitive ® 1-9 
doctype-independent® 1—8 
doctype-specific ® 1-8 
for mathematical quantities 
See <MATH> 
using ®3—1 to 3-22 
/TAG_TRANSLATOR qualifier © A—16 
Text elements 
creating 
See Tags, using 
definition of ¢ 2-1 
/TEXT_FORMATTER qualifier © A—16 
<TILDE> 
in math expressions ® 9-146 
<TILDE_CHAR> 
in math expressions ® 9-146 
<TITLE> 
definition of * 9-244 
Title page 
creating ® 3-3 
<TITLE_PAGE> 
definition of * 9-245 
Trademarks, creating 
see <FOOTNOTE> 
See <SPECIAL_CHAR> 
Troubleshooting output problems ® 5-3 
missing spaces in code examples ® 5-3 
paragraph spacing ® 5-3 
problems with examples ¢ 5-3. 
sequencing of formal elements * 5—4 


U 


<U> 

definition of © 9-246 
<UNDERLINE> 

definition of © 9-247 





<UNDERLINE> (cont’d.) 

in math expressions ® 9-146 
<UPDATE_RANGE > 

definition of ©9-248 to 9-250 
<UPPERCASE> 

definition of °9-251 
<USER_I_MESSAGE> 

definition of ©9—252 to 9-253 
<USER_W_MESSAGE> 

definition of ©9—254 to 9-255 


V 


<VALID_BREAK> 
definition of ° 9-256 
<VALID_TABLE_ROW_BREAK > 
definition of °9-—257 
<VARIABLE> 
definition of ©9-258 
VAX DOCUMENT 
See DOCUMENT command 


<VBAR> 

definition of 9-259 
<VECTOR> 

in math expressions ® 9-146 
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Vertical bar or ampersand 
coding a® 2-6 


X 


<X> 
definition of ¢9-260 to 9-263 
using to create index entries © 7-2 
XREF file * 6-2 
<xS> 
See <x> 
See <yY> 
<XSUBENTRY > 
See <x> 
See <y> 


Y 


<Y¥> 
definition of ©9-—264 to 9-265 
using to create index cross-references ® 7—2 
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Please use this postage-paid form to comment on this manual. If you require a written reply to a software 
problem and are eligible to receive one under Software Performance Report (SPR) service, submit your 
comments on an SPR form. 


Thank you for your assistance. 


I rate this manual’s: Excellent Good Fair Poor 


Accuracy (software works as manual says) 
Completeness (enough information) 
Clarity (easy to understand) 
Organization (structure of subject matter) 
- Figures (useful) 
Examples (useful) 
Index (ability to find topic) 
Page layout (easy to find information) 


OOOO0O0000 
OOOOo000o 
OOOOO000 
OOOOO0000 


I would like to see more/less 
What I like best about this manual is 


What I like least about this manual is 


I found the following errors in this manual: 


J 

» 
18°) 

® 


Description 








Additional comments or suggestions to improve this manual: 


I am using Version of the software this manual describes. 
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